update documentation after API changes

doc/developers/bootstrap.rst

@@ -13,6 +13,9 @@ infrastructure files which will be needed to build the project::
   $ mkdir cmake  # does not have to be called "cmake" - take the name you prefer
   $ cd cmake
   $ wget https://github.com/coderefinery/autocmake/raw/master/update.py
+  $ virtualenv venv
+  $ source venv/bin/activate
+  $ pip install pyyaml
   $ python update.py --self
 
 On the MS Windows system, you can use the PowerShell wget-replacement::

doc/developers/configuration.rst

@@ -1,115 +1,101 @@
 
 .. _autocmake_yml:
 
-Configuring autocmake.cfg
+Configuring autocmake.yml
 =========================
 
-The script ``autocmake.cfg`` is the high level place where you configure
+The script ``autocmake.yml`` is the high level place where you configure
 your project. Here is an example. We will discuss it in detail further
 below::
 
-  [project]
   name: numgrid
+
   min_cmake_version: 2.8
 
-  [fc]
+  url_root: https://github.com/coderefinery/autocmake/raw/master/
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/fc.cmake
 
-  [cc]
+  modules:
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/cc.cmake
+  - compilers:
-
+    - source:
-  [cxx]
+      - '%(url_root)modules/fc.cmake'
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/cxx.cmake
+      - '%(url_root)modules/cc.cmake'
-
+      - '%(url_root)modules/cxx.cmake'
-  [flags]
+  - flags:
-  source: https://github.com/coderefinery/autocmake/raw/master/compilers/GNU.CXX.cmake
+    - source:
-          https://github.com/coderefinery/autocmake/raw/master/compilers/Intel.CXX.cmake
+      - '%(url_root)compilers/GNU.CXX.cmake'
-
+      - '%(url_root)compilers/Intel.CXX.cmake'
-  [rpath]
+      - 'compilers/Clang.CXX.cmake'
-  source: custom/rpath.cmake
+  - plugins:
-
+    - source:
-  [definitions]
+      - '%(url_root)modules/ccache.cmake'
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/definitions.cmake
+      - 'custom/rpath.cmake'
-
+      - '%(url_root)modules/definitions.cmake'
-  [coverage]
+      - '%(url_root)modules/code_coverage.cmake'
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/code_coverage.cmake
+      - '%(url_root)modules/safeguards.cmake'
-
+      - '%(url_root)modules/default_build_paths.cmake'
-  [safeguards]
+      - '%(url_root)modules/src.cmake'
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/safeguards.cmake
+      - '%(url_root)modules/googletest.cmake'
-
+      - 'custom/api.cmake'
-  [default_build_paths]
+      - 'custom/test.cmake'
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/default_build_paths.cmake
-
-  [src]
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake
-
-  [googletest]
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/googletest.cmake
-
-  [custom]
-  source: custom/api.cmake
-          custom/test.cmake
 
 
 Name and order of sections
 --------------------------
 
-We see that the configuration file has sections.
+First we define the project name (here "numgrid"). This section has to be there
-The only section where the name matters is ``[project]``::
+and it has to be called "project" (but it does not have to be on top).
 
-  [project]
+We also have to define ``min_cmake_version``.
-  name: numgrid
-  min_cmake_version: 2.8
 
-This is where we define the project name (here "numgrid"). This section has to
+The definition ``url_root`` is an interpolation (see :ref:`interpolation`) and
-be there and it has to be called "project" (but it does not have to be on top).
+we use it to avoid retyping the same line over and over and to be able to
+change it in one place.  The explicit name "url_root" has no special meaning to
+Autocmake and we could have chosen a different name.
 
-The names of the other sections do not matter to Autocmake. You could name them like this::
+The section ``modules`` is a list of CMake plugins.  The names of the list
+elements (here "compilers", "flags", and "plugins") does not matter to
+Autocmake. We could have called them "one", "two", and "whatever", but it would
+not make much sense. It is better to choose names that are meaningful to you
+and readers of your code.
 
-  [project]
+The order of the elements under ``modules`` does matter and the list will be
-  name: numgrid
+processed in the exact order as you specify them in ``autocmake.yml``.
-  min_cmake_version: 2.8
-
-  [one]
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/fc.cmake
-
-  [two]
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/cc.cmake
-
-  [whatever]
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/cxx.cmake
-
-But it would not make much sense. It is better to choose names that are
-meaningful to you.
-
-The order of the sections does matter and the sections will be processed in the
-exact order as you specify them in ``autocmake.cfg``.
 
 
 Minimal example
 ---------------
 
-As a minimal example we take an ``autocmake.cfg`` which only contains::
+As a minimal example we take an ``autocmake.yml`` which only contains::
 
-  [project]
   name: minime
   min_cmake_version: 2.8
 
+If you don't have the ``update.py`` script yet, you need to fetch it from the web::
+
+  $ wget https://github.com/coderefinery/autocmake/raw/master/update.py
+
 First we make sure that the ``update.py`` script is up-to-date and that it has access
 to all libraries it needs::
 
   $ python update.py --self
 
   - creating .gitignore
-  - fetching lib/config.py
+  - fetching autocmake/configure.py
-  - fetching lib/docopt/docopt.py
+  - fetching autocmake/__init__.py
+  - fetching autocmake/external/docopt.py
+  - fetching autocmake/external/__init__.py
+  - fetching autocmake/generate.py
+  - fetching autocmake/extract.py
+  - fetching autocmake/interpolate.py
+  - fetching autocmake/parse_rst.py
+  - fetching autocmake/parse_yaml.py
   - fetching update.py
 
 Good. Now we can generate ``CMakeLists.txt`` and the setup script::
 
-  $ python update ..
+  $ python update.py ..
 
-  - parsing autocmake.cfg
+  - parsing autocmake.yml
   - generating CMakeLists.txt
   - generating setup script
 
@@ -147,38 +133,38 @@ the following default options::
     --show                                 Show CMake command and exit.
     --cmake-executable=<CMAKE_EXECUTABLE>  Set the CMake executable [default: cmake].
     --cmake-options=<STRING>               Define options to CMake [default: ''].
+    --prefix=<PATH>                        Set the install path for make install.
     <builddir>                             Build directory.
     -h --help                              Show this screen.
 
 That's not too bad although currently we cannot do much with this since there
 are no sources listed, no targets, hence nothing to build. We need to flesh out
-``CMakeLists.txt`` by extending ``autocmake.cfg``
+``CMakeLists.txt`` by extending ``autocmake.yml`` and this is what we will do
-and this is what we will do in the next section.
+in the next section.
 
 
 Assembling CMake plugins
 ------------------------
 
-The preferred way to extend ``CMakeLists.txt`` is by editing ``autocmake.cfg``
+The preferred way to extend ``CMakeLists.txt`` is by editing ``autocmake.yml``
 and using the ``source`` option::
 
-  [fc]
+  - compilers:
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/fc.cmake
+    - source:
+      - '%(url_root)modules/fc.cmake'
+      - '%(url_root)modules/cc.cmake'
+      - '%(url_root)modules/cxx.cmake'
 
-This will download ``fc.cmake`` and include it in ``CMakeLists.txt``.
+This will download ``fc.cmake``, ``cc.cmake``, and ``cxx.cmake``, and include
+them in ``CMakeLists.txt``, in this order.
 
 You can also include local CMake modules, e.g.::
 
-  [rpath]
+  - source:
-  source: custom/rpath.cmake
+    - 'custom/rpath.cmake'
 
-It is also OK to include several modules at once::
+It is also OK to include several modules at once as we have seen above.  The
-
+modules will be included in the same order as they appear in ``autocmake.yml``.
-  [flags]
-  source: https://github.com/coderefinery/autocmake/raw/master/compilers/GNU.CXX.cmake
-          https://github.com/coderefinery/autocmake/raw/master/compilers/Intel.CXX.cmake
-
-The modules will be included in the same order as they appear in ``autocmake.cfg``.
 
 
 Fetching files without including them in CMakeLists.txt
@@ -187,9 +173,9 @@ Fetching files without including them in CMakeLists.txt
 Sometimes you want to fetch a file without including it in ``CMakeLists.txt``.
 This can be done with the ``fetch`` option.  This is for instance done by the
 ``git_info.cmake`` module (see
-https://github.com/coderefinery/autocmake/blob/master/modules/git_info/git_info.cmake#L10-L11).
+https://github.com/coderefinery/autocmake/blob/master/modules/git_info/git_info.cmake#L10-L13).
 
-If ``fetch`` is invoked in ``autocmake.cfg``, then the fetched file is placed
+If ``fetch`` is invoked in ``autocmake.yml``, then the fetched file is placed
 under ``downloaded/``.  If ``fetch`` is invoked from within a CMake module
 documentation (see below), then the fetched file is placed into the same
 directory as the CMake module file which fetches it.
@@ -199,11 +185,11 @@ Generating setup options
 ------------------------
 
 Options for the setup script can be generated with the ``docopt``
-option. As an example, the following ``autocmake.cfg`` snippet will add a
+option. As an example, the following ``autocmake.yml`` snippet will add a
 ``--something`` flag::
 
-  [my_section]
+  - my_section:
-  docopt: --something Enable something [default: False].
+    - docopt: "--something Enable something [default: False]."
 
 
 Setting CMake options
@@ -213,9 +199,9 @@ Configure-time CMake options can be generated with the ``define`` option.
 Consider the following example which toggles the CMake variable
 ``ENABLE_SOMETHING``::
 
-  [my_section]
+  - my_section:
-  docopt: --something Enable something [default: False].
+    - docopt: "--something Enable something [default: False]."
-  define: '-DENABLE_SOMETHING={0}'.format(arguments['--something'])
+    - define: "'-DENABLE_SOMETHING={0}'.format(arguments['--enable-something'])"
 
 
 Setting environment variables
@@ -224,33 +210,23 @@ Setting environment variables
 You can export environment variables at configure-time using the ``export``
 option. Consider the following example::
 
-  [cc]
+  docopt:
-  docopt: --cc=<CC> C compiler [default: gcc].
+    - "--cc=<CC> C compiler [default: gcc]."
-          --extra-cc-flags=<EXTRA_CFLAGS> Extra C compiler flags [default: ''].
+    - "--extra-cc-flags=<EXTRA_CFLAGS> Extra C compiler flags [default: '']."
-  export: 'CC=%s' % arguments['--cc']
+  export: "'CC={0}'.format(arguments['--cc'])"
-  define: '-DEXTRA_CFLAGS="%s"' % arguments['--extra-cc-flags']
+  define: "'-DEXTRA_CFLAGS=\"{0}\"'.format(arguments['--extra-cc-flags'])"
 
 
 Auto-generating configurations from the documentation
 -----------------------------------------------------
 
-To avoid a boring re-typing of boilerplate ``autocmake.cfg`` code it is possible
+To avoid a boring re-typing of boilerplate ``autocmake.yml`` code it is possible
 to auto-generate configurations from the documentation. This is the case
 for many core modules which come with own options once you have sourced them.
 
-The lines following ``# autocmake.cfg configuration::`` are
+The lines following ``# autocmake.yml configuration::`` are
-understood by the ``update.py`` script to infer ``autocmake.cfg`` code from the
+understood by the ``update.py`` script to infer ``autocmake.yml`` code from the
 documentation. As an example consider
-https://github.com/coderefinery/autocmake/blob/master/modules/cc.cmake#L20-L25.
+https://github.com/coderefinery/autocmake/blob/master/modules/cc.cmake#L20-L26.
 Here, ``update.py`` will infer the configurations for ``docopt``, ``export``,
 and ``define``.
-
-
-Overriding documented configurations
-------------------------------------
-
-Configurable documented defaults can be achieved using interpolations.  See for
-instance
-https://github.com/coderefinery/autocmake/blob/master/modules/boost/boost.cmake#L33-L36.
-These can be modified within ``autocmake.cfg`` with a dictionary, e.g.:
-https://github.com/coderefinery/autocmake/blob/master/test/boost_libs/cmake/autocmake.cfg#L9

doc/developers/customizing-modules.rst

@@ -47,8 +47,8 @@ Settings in ``autocmake.yml`` take precedence over
 settings imported by a sourced module.
 
 As an example consider the Boost module which defines and uses
-interpolation variables ``major``, ``minor``, and ``patch``, see
+interpolation variables ``major``, ``minor``, ``patch``, and ``components``, see
-https://github.com/coderefinery/autocmake/blob/master/modules/boost/boost.cmake#L52-L54.
+https://github.com/coderefinery/autocmake/blob/master/modules/boost/boost.cmake#L52-L55.
 
 The recommended way to customize these is in ``autocmake.yml``, e.g.:
 https://github.com/coderefinery/autocmake/blob/master/test/boost_libs/cmake/autocmake.yml#L12-L17.

doc/developers/example.rst

@@ -1,6 +1,6 @@
 
 
-Example Hello World project
+Example hello world project
 ===========================
 
 This is a brief example for the busy and impatient programmer. For a longer
@@ -23,40 +23,49 @@ there. This is not necessary for Autocmake but it is a generally good practice::
 
 Now we create ``cmake/`` and fetch ``update.py``::
 
-  $ mkdir cmake
+  $ mkdir cmake  # does not have to be called "cmake" - take the name you prefer
-  $ cd cmake/
+  $ cd cmake
-  $ wget https://raw.githubusercontent.com/coderefinery/autocmake/master/update.py
+  $ wget https://github.com/coderefinery/autocmake/raw/master/update.py
   $ python update.py --self
 
 Now from top-level our file tree looks like this::
 
   .
   |-- cmake
-  |   |-- autocmake.cfg
+  |   |-- autocmake
-  |   |-- lib
+  |   |   |-- __init__.py
-  |   |   |-- config.py
+  |   |   |-- configure.py
-  |   |   `-- docopt
+  |   |   |-- external
-  |   |       `-- docopt.py
+  |   |   |   |-- __init__.py
+  |   |   |   `-- docopt.py
+  |   |   |-- extract.py
+  |   |   |-- generate.py
+  |   |   |-- interpolate.py
+  |   |   |-- parse_rst.py
+  |   |   `-- parse_yaml.py
+  |   |-- autocmake.yml
   |   `-- update.py
   `-- src
       |-- feature1.F90
       |-- feature2.c
       `-- main.F90
 
-Now we edit ``cmake/autocmake.cfg`` to look like this::
+Now we edit ``cmake/autocmake.yml`` to look like this::
 
-  [project]
   name: hello
+
   min_cmake_version: 2.8
 
-  [fc]
+  url_root: https://github.com/coderefinery/autocmake/raw/master/
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/fc.cmake
 
-  [cc]
+  modules:
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/cc.cmake
+  - compilers:
-
+    - source:
-  [src]
+      - '%(url_root)modules/fc.cmake'
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake
+      - '%(url_root)modules/cc.cmake'
+  - src_support:
+    - source:
+      - '%(url_root)modules/src.cmake'
 
 What we have specified here is the project name and that we wish Fortran and C
 support. The ``src.cmake`` module tells CMake to include a ``src/CMakeLists.txt``.
@@ -76,20 +85,32 @@ Now we have everything to generate ``CMakeLists.txt`` and a setup script::
   $ cd cmake
   $ python update ..
 
+  - parsing autocmake.yml
+  - assembling modules: [##############################] (3/3)
+  - generating CMakeLists.txt
+  - generating setup script
+
 And this is what we got::
 
   .
   |-- CMakeLists.txt
   |-- cmake
-  |   |-- autocmake.cfg
+  |   |-- autocmake
+  |   |   |-- __init__.py
+  |   |   |-- configure.py
+  |   |   |-- external
+  |   |   |   |-- __init__.py
+  |   |   |   `-- docopt.py
+  |   |   |-- extract.py
+  |   |   |-- generate.py
+  |   |   |-- interpolate.py
+  |   |   |-- parse_rst.py
+  |   |   `-- parse_yaml.py
+  |   |-- autocmake.yml
   |   |-- downloaded
   |   |   |-- autocmake_cc.cmake
   |   |   |-- autocmake_fc.cmake
   |   |   `-- autocmake_src.cmake
-  |   |-- lib
-  |   |   |-- config.py
-  |   |   `-- docopt
-  |   |       `-- docopt.py
   |   `-- update.py
   |-- setup
   `-- src
@@ -100,12 +121,12 @@ And this is what we got::
 
 Now we are ready to build::
 
-  $ python setup --fc=gfortran --cc=gcc
+  $ ./setup --fc=gfortran --cc=gcc
 
-  FC=gfortran CC=gcc cmake -DEXTRA_FCFLAGS="''" -DENABLE_FC_SUPPORT="ON" -DEXTRA_CFLAGS="''" -DCMAKE_BUILD_TYPE=release -G "Unix Makefiles" None /home/user/example
+  FC=gfortran CC=gcc cmake -DEXTRA_FCFLAGS="''" -DEXTRA_CFLAGS="''" -DCMAKE_BUILD_TYPE=release -G "Unix Makefiles" /home/user/hello
 
-  -- The C compiler identification is GNU 4.9.2
+  -- The C compiler identification is GNU 6.1.1
-  -- The CXX compiler identification is GNU 4.9.2
+  -- The CXX compiler identification is GNU 6.1.1
   -- Check for working C compiler: /usr/bin/gcc
   -- Check for working C compiler: /usr/bin/gcc -- works
   -- Detecting C compiler ABI info
@@ -118,7 +139,7 @@ Now we are ready to build::
   -- Detecting CXX compiler ABI info - done
   -- Detecting CXX compile features
   -- Detecting CXX compile features - done
-  -- The Fortran compiler identification is GNU 4.9.2
+  -- The Fortran compiler identification is GNU 6.1.1
   -- Check for working Fortran compiler: /usr/bin/gfortran
   -- Check for working Fortran compiler: /usr/bin/gfortran  -- works
   -- Detecting Fortran compiler ABI info
@@ -127,14 +148,14 @@ Now we are ready to build::
   -- Checking whether /usr/bin/gfortran supports Fortran 90 -- yes
   -- Configuring done
   -- Generating done
-  -- Build files have been written to: /home/user/example/build
+  -- Build files have been written to: /home/user/hello/build
 
      configure step is done
      now you need to compile the sources:
      $ cd build
      $ make
 
-  $ cd build/
+  $ cd build
   $ make
 
   Scanning dependencies of target hello.x

doc/developers/faq.rst

@@ -4,6 +4,18 @@ FAQ for developers
 ==================
 
 
+Which files do I need to edit?
+------------------------------
+
+Let us start with files which you normally never edit: ``CMakeLists.txt`` and
+``setup`` - these are generated based on ``autocmake.yml``. Have a look in
+``autocmake.yml`` and you will see all CMake files which are assembled into
+``CMakeLists.txt``.  You can edit those files. If you change the order of files
+listed in ``autocmake.yml`` or if you add or remove CMake modules, then you
+need to rerun the ``update.py`` script to refresh ``CMakeLists.txt`` and
+``setup``.
+
+
 Autocmake does not do feature X - I really need feature X and a setup flag --X
 ------------------------------------------------------------------------------
 
@@ -19,18 +31,22 @@ naming)::
 
   cmake/custom/my_feature.cmake
 
-And include this feature to the main ``CMakeLists.txt`` in ``autocmake.cfg``::
+And include this feature to the main ``CMakeLists.txt`` in ``autocmake.yml``
+under the ``modules`` section::
 
-  [my_feature]
+  modules:
-  source: custom/my_feature.cmake
+  - my_feature:
+    - source:
+      - custom/my_feature.cmake
 
 Now your code is included in the main ``CMakeLists.txt``. Perhaps you also
 want a setup script flag to toggle the feature::
 
-  [my_feature]
+  - my_feature:
-  source: custom/my_feature.cmake
+    - docopt: "--enable-my-feature Enable my feature [default: False]."
-  docopt: --my-feature Enable my feature [default: False].
+    - define: "'-DENABLE_MY_FEATURE={0}'.format(arguments['--enable-my-feature'])"
-  define: '-DENABLE_MY_FEATURE={0}'.format(arguments['--my-feature'])
+    - source:
+      - custom/my_feature.cmake
 
 Implement your ideas, test them, and share them.  If your module is portable,
 good code quality, and of general interest, you can suggest it to be part of
@@ -43,17 +59,16 @@ How can I get a setup flag --X that toggles a CMake variable?
 The following will add a ``--something`` flag which toggles the CMake variable
 ``ENABLE_SOMETHING``::
 
-  [my_section]
+  - my_section:
-  docopt: --something Enable something [default: False].
+    - docopt: "--something Enable something [default: False]."
-  define: '-DENABLE_SOMETHING={0}'.format(arguments['--something'])
+    - define: "'-DENABLE_SOMETHING={0}'.format(arguments['--enable-something'])"
 
 
 Can I change the name of the setup script?
 ------------------------------------------
 
-Yes you can do that in ``autocmake.cfg``. Here we for instance change the name to "configure"::
+Yes you can do that in ``autocmake.yml``. Here we for instance change the name to "configure"::
 
-  [project]
   name: myproject
   min_cmake_version: 2.8
   setup_script: configure
@@ -70,12 +85,13 @@ realized in Autocmake.
 Should I include and track also files generated by Autocmake in my repository?
 ------------------------------------------------------------------------------
 
-Yes, you probably want to do that. Autocmake generates a number of files which
+Yes, you probably want to do that. Autocmake downloads and generates a number
-in principle could be generated at configure- or build-time.  However, you
+of files which in principle could be generated at configure- or build-time.
-probably do not want the users of your code to run any Autocmake scripts like
+However, you probably do not want the users of your code to run any Autocmake
-``update.py`` to generate the files they need to build the project. The users
+scripts like ``update.py`` to generate the files they need to build the
-of your code will run ``setup`` directly and expect everything to just work
+project. The users of your code will run ``setup`` directly and typically expect
-(TM).
+everything to just work (TM). Note also that the users of your code will
+not need to install the pyyaml package.
 
 
 The update.py script is overwriting my CMakeLists.txt and setup, isn't this bad?
@@ -93,7 +109,7 @@ But I need to manually edit and customize CMakeLists.txt and setup every time I
 -----------------------------------------------------------------------------------------------
 
 You typically never need to manually edit and customize ``CMakeLists.txt`` and
-``setup`` directly. You can introduce customizations in ``autocmake.cfg``
+``setup`` directly. You can introduce customizations in ``autocmake.yml``
 which get assembled into the front-end scripts.
 
 
@@ -101,19 +117,21 @@ Where is a good place to list my sources and targets?
 -----------------------------------------------------
 
 As mentioned above ``CMakeLists.txt`` is not a good place because this file is
-generated from ``autocmake.cfg`` and your modifications would become
+generated from ``autocmake.yml`` and your modifications would become
 overwritten at some point.  A good standard is to organize your sources under
 ``src/`` and to list your sources and targets in ``src/CMakeLists.txt``.  You
-can include the latter in ``autocmake.cfg`` using::
+can include the latter in ``autocmake.yml`` using::
 
-  [src]
+  - my_sources:
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake
+    - source:
+      - https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake
 
-If you really don't like to do it this way, you can describe your sources and
+If you really do not like to do it this way, you can describe your sources and
 targets in a custom module in a local file and include it like this::
 
-  [my_sources]
+  - my_sources:
-  source: custom/my_sources.cmake
+    - source:
+      - custom/my_sources.cmake
 
 
 How can I do some more sophisticated validation of setup flags?
@@ -121,7 +139,7 @@ How can I do some more sophisticated validation of setup flags?
 
 Sometimes you need to do more sophisticated validation and post-processing
 of setup flags. This can be done by placing a module called ``extensions.py``
-under ``cmake/`` (or wherever you have ``autocmake.cfg``).
+under ``cmake/`` (or wherever you have ``autocmake.yml``).
 This file should implement a function with the following signature:
 
 .. code-block:: python

doc/developers/interpolation.rst

@@ -0,0 +1,34 @@
+
+.. _interpolation:
+
+Interpolation
+=============
+
+In a custom extension to the YAML specification you can define and reuse
+variables like this (observe how we interpolate ``url_root``, ``major``,
+``minor``, ``patch``, and ``components`` in this example)::
+
+  url_root: https://github.com/coderefinery/autocmake/raw/master/
+  major: 1
+  minor: 48
+  patch: 0
+  components: ""
+  fetch:
+    - "%(url_root)modules/boost/boost_unpack.cmake"
+    - "%(url_root)modules/boost/boost_userconfig.cmake"
+    - "%(url_root)modules/boost/boost_configure.cmake"
+    - "%(url_root)modules/boost/boost_build.cmake"
+    - "%(url_root)modules/boost/boost_install.cmake"
+    - "%(url_root)modules/boost/boost_headers.cmake"
+    - "%(url_root)modules/boost/boost_cleanup.cmake"
+    - "http://sourceforge.net/projects/boost/files/boost/%(major).%(minor).%(patch)/boost_%(major)_%(minor)_%(patch).zip"
+  docopt:
+    - "--boost-headers=<BOOST_INCLUDEDIR> Include directories for Boost [default: '']."
+    - "--boost-libraries=<BOOST_LIBRARYDIR> Library directories for Boost [default: '']."
+    - "--build-boost=<FORCE_CUSTOM_BOOST> Deactivate Boost detection and build on-the-fly <ON/OFF> [default: OFF]."
+  define:
+    - "'-DBOOST_INCLUDEDIR=\"{0}\"'.format(arguments['--boost-headers'])"
+    - "'-DBOOST_LIBRARYDIR=\"{0}\"'.format(arguments['--boost-libraries'])"
+    - "'-DFORCE_CUSTOM_BOOST={0}'.format(arguments['--build-boost'])"
+    - "'-DBOOST_MINIMUM_REQUIRED=\"%(major).%(minor).%(patch)\"'"
+    - "'-DBOOST_COMPONENTS_REQUIRED=\"%(components)\"'"

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::
 
-  [foo]
+  - my_feature:
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/foo.cmake
+    - source: https://github.com/coderefinery/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)::
 
-  [foo]
+  - my_feature:
-  source: https://github.com/coderefinery/autocmake/raw/abcd123/modules/foo.cmake
+    - source: https://github.com/coderefinery/autocmake/raw/abcd123/modules/foo.cmake

doc/general/about.rst

@@ -38,7 +38,7 @@ file::
   Build/install/test targets
 
 Our main motivation to create Autocmake as a CMake framework library and
-CMake module composer is to simplify CMake code transfer between codes. We got
+CMake module composer is to simplify CMake code transfer between programs. We got
 tired of manually diffing and copy-pasting boiler-plate CMake code and watching
 it diverge while maintaining the CMake infrastructure in a growing number of
 scientific projects which typically have very similar requirements:

doc/general/requirements.rst

@@ -8,3 +8,6 @@ support Python 3 (we automatically test with 2.7 and 3.5).
 
 The generated setup script runs with Python >= 2.6 (also tested with Python
 3.5).
+
+To generate ``CMakeLists.txt`` and the ``setup`` script, Autocmake
+requires the pyyaml package.

doc/index.rst

@@ -1,7 +1,7 @@
 
 
-Autocmake (this documentation is outdated, see stable-0.x branch)
+Autocmake
-=================================================================
+=========
 
 
 General
@@ -27,6 +27,7 @@ For developers who use Autocmake
    developers/example.rst
    developers/customizing-modules.rst
    developers/updating-modules.rst
+   developers/interpolation.rst
 
 
 For users of projects which use Autocmake

doc/users/faq.rst

@@ -49,9 +49,7 @@ Like this::
 
   $ python setup --cmake-options='"-DTHIS_OPTION=ON -DTHAT_OPTION=OFF"'
 
-We use two sets of quotes because the shell swallows one set of them
+We use two sets of quotes because the shell swallows one set of them before
-before passing the arguments to Python. Yeah that's not nice, but nothing
+passing the arguments to Python. Yeah that's not nice, but nothing we can do
-we can do about it on the Python side.
+about it on the Python side. If you do not use two sets of quotes then the
-If you do not use two sets
+setup command may end up incorrectly saved in `build/setup_command`.
-of quotes then the setup command may end up
-incorrectly saved in `build/setup_command`.