update documentation after API changes

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]
-  source: custom/my_feature.cmake
+  modules:
+  - 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]
-  source: custom/my_feature.cmake
-  docopt: --my-feature Enable my feature [default: False].
-  define: '-DENABLE_MY_FEATURE={0}'.format(arguments['--my-feature'])
+  - my_feature:
+    - docopt: "--enable-my-feature Enable my feature [default: False]."
+    - define: "'-DENABLE_MY_FEATURE={0}'.format(arguments['--enable-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]
-  docopt: --something Enable something [default: False].
-  define: '-DENABLE_SOMETHING={0}'.format(arguments['--something'])
+  - my_section:
+    - docopt: "--something Enable something [default: False]."
+    - 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
-in principle could be generated at configure- or build-time.  However, you
-probably do not want the users of your code to run any Autocmake scripts like
-``update.py`` to generate the files they need to build the project. The users
-of your code will run ``setup`` directly and expect everything to just work
-(TM).
+Yes, you probably want to do that. Autocmake downloads and generates a number
+of files which in principle could be generated at configure- or build-time.
+However, you probably do not want the users of your code to run any Autocmake
+scripts like ``update.py`` to generate the files they need to build the
+project. The users of your code will run ``setup`` directly and typically expect
+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]
-  source: https://github.com/coderefinery/autocmake/raw/master/modules/src.cmake
+  - my_sources:
+    - 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]
-  source: custom/my_sources.cmake
+  - my_sources:
+    - 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