update doc for developers

doc/developers/bootstrap.rst

@@ -15,7 +15,7 @@ infrastructure files which will be needed to build the project::
   $ wget https://github.com/scisoft/autocmake/raw/master/update.py
   $ python update.py --self
 
-On the MS Windows system, use the PowerShell wget-replacement::
+On the MS Windows system, you can use the PowerShell wget-replacement::
 
   $ Invoke-WebRequest https://github.com/scisoft/autocmake/raw/master/update.py -OutFile update.py
 
@@ -23,13 +23,14 @@ This creates (or updates) the following files (an existing ``autocmake.cfg`` is
 not overwritten by the script)::
 
   cmake/
-      update.py      # no need to edit
+      autocmake.cfg      # edit this file
-      autocmake.cfg  # edit this file
+      update.py          # no need to edit
       lib/
-          config.py  # no need to edit
+          config.py      # no need to edit
-          docopt.py  # no need to edit
+          docopt/
+              docopt.py  # no need to edit
 
-Note that all other listed files are overwritten (use version control!).
+Note that all other listed files are overwritten (use version control).
 
 
 Generating the CMake infrastructure
@@ -38,7 +39,7 @@ Generating the CMake infrastructure
 Now customize ``autocmake.cfg`` to your needs
 (see :ref:`autocmake_cfg`)
 and then run the ``update.py`` script which
-creates ``CMakeLists.txt`` and ``setup.py``::
+creates ``CMakeLists.txt`` and ``setup.py`` in the target path::
 
   $ python update.py ..
 
@@ -46,12 +47,13 @@ The script also downloads external CMake modules specified in ``autocmake.cfg``
 called ``downloaded/``::
 
   cmake/
-      update.py
+      autocmake.cfg      # edit this file
-      autocmake.cfg
+      update.py          # no need to edit
       lib/
-          config.py
+          config.py      # no need to edit
-          docopt.py
+          docopt/
-          downloaded/  # contains CMake modules fetched from the web
+              docopt.py  # no need to edit
+          downloaded/    # contains CMake modules fetched from the web
 
 
 Building the project

doc/developers/customizing-modules.rst

@@ -5,7 +5,7 @@ Customizing CMake modules
 
 The ``update.py`` script assembles modules listed in ``autocmake.cfg`` into
 ``CMakeLists.txt``. Those that are fetched from the web are placed inside
-``downloaded/``.  You have at least four options to customize downloaded CMake
+``downloaded/``.  You have several options to customize downloaded CMake
 modules:
 
 
@@ -20,12 +20,29 @@ the least elegant solution since the customizations may be overwritten by the
 Adapt local copies of CMake modules
 -----------------------------------
 
-A better solution is to download the CMake modules that you wish you customize
+A slightly better solution is to download the CMake modules that you wish you customize
 to a separate directory (e.g. ``custom/``) and source the customized CMake
 modules in ``autocmake.cfg``. Alternatively you can serve your custom modules
 from your own http server.
 
 
+Fork and branch the CMake modules
+---------------------------------
+
+You can fork and branch the mainline Autocmake development and include
+the branched customized versions. This will make it easier for you
+to stay up-to-date with upstream development.
+
+
+Overriding defaults
+-------------------
+
+Some modules use interpolations to set defaults, see for instance
+https://github.com/scisoft/autocmake/blob/master/modules/boost/boost.cmake#L33-L36.
+These can be modified within ``autocmake.cfg``, e.g.:
+https://github.com/scisoft/autocmake/blob/master/test/boost_libs/cmake/autocmake.cfg#L9
+
+
 Create own CMake modules
 ------------------------
 

doc/developers/example.rst

@@ -35,7 +35,8 @@ Now from top-level our file tree looks like this::
   |   |-- autocmake.cfg
   |   |-- lib
   |   |   |-- config.py
-  |   |   `-- docopt.py
+  |   |   `-- docopt
+  |   |       `-- docopt.py
   |   `-- update.py
   `-- src
       |-- feature1.F90
@@ -46,6 +47,7 @@ Now we edit ``cmake/autocmake.cfg`` to look like this::
 
   [project]
   name: hello
+  min_cmake_version: 2.8
 
   [fc]
   source: https://github.com/scisoft/autocmake/raw/master/modules/fc.cmake
@@ -57,7 +59,7 @@ Now we edit ``cmake/autocmake.cfg`` to look like this::
   source: https://github.com/scisoft/autocmake/raw/master/modules/src.cmake
 
 What we have specified here is the project name and that we wish Fortran and C
-support. The ``[src]`` module tells CMake to include a ``src/CMakeLists.txt``.
+support. The ``src.cmake`` module tells CMake to include a ``src/CMakeLists.txt``.
 We need to create ``src/CMakeLists.txt`` which can look like this::
 
   add_executable(
@@ -86,7 +88,8 @@ And this is what we got::
   |   |   `-- autocmake_src.cmake
   |   |-- lib
   |   |   |-- config.py
-  |   |   `-- docopt.py
+  |   |   `-- docopt
+  |   |       `-- docopt.py
   |   `-- update.py
   |-- setup.py
   `-- src
@@ -144,5 +147,5 @@ Now we are ready to build::
 Excellent! But this was a lot of typing and file creating just to get a simple
 executable compiled!? Of course, all that could have been done with few command
 lines directly but now we have a cross-platform project and can extend it and
-customize it and we got a front-end script and command-line parser for free.
+customize it and we also got a front-end script and command-line parser for free.
 Now go out and explore more Autocmake modules and features.

doc/developers/updating-modules.rst

@@ -20,11 +20,11 @@ Sometimes you may want to avoid using the latest version of a CMake module and
 rather fetch an older version, for example with the hash ``abcd123``. To
 achieve this, instead of::
 
-  [coverage]
+  [foo]
-  source: https://github.com/scisoft/autocmake/raw/master/modules/code_coverage.cmake
+  source: https://github.com/scisoft/autocmake/raw/master/modules/foo.cmake
 
 pin the version to ``abcd123`` (you do not need to specify the full Git hash, a unique
 beginning will do)::
 
-  [coverage]
+  [foo]
-  source: https://github.com/scisoft/autocmake/raw/abcd123/modules/code_coverage.cmake
+  source: https://github.com/scisoft/autocmake/raw/abcd123/modules/foo.cmake