adapt doc directory tree structure

doc/developers/customizing-modules.rst

@@ -0,0 +1,41 @@
+
+
+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
+modules:
+
+
+Directly inside the generated directory
+---------------------------------------
+
+The CMake modules can be customized directly inside ``downloaded/`` but this is
+the least elegant solution since the customizations may be overwritten by the
+``update.py`` script (use version control).
+
+
+Adapt local copies of CMake modules
+-----------------------------------
+
+A better solution is to download the CMake modules that you wish you customize
+to a separate directory and source the customized CMake modules in
+``autocmake.cfg``. Alternatively you can serve your custom
+modules from your own http server.
+
+
+Create own CMake modules
+------------------------
+
+Of course you can also create own modules and source them in ``autocmake.cfg``.
+
+
+Contribute customizations to the "standard library"
+---------------------------------------------------
+
+If you think that your customization will be useful for other users as well,
+you may consider contributing the changes directly to
+https://github.com/scisoft/autocmake/. We very much encourage such
+contributions. But we also strive for generality and portability.

doc/developers/faq.rst

@@ -0,0 +1,51 @@
+
+
+FAQ
+===
+
+
+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. They will
+run ``setup.py`` directly and expect everything to just work (TM).
+
+
+The update.py script is overwriting my CMakeLists.txt and setup.py, isn't this bad?
+-----------------------------------------------------------------------------------
+
+It's not as bad as it first looks. It's a feature. Normally ``CMakeLists.txt``
+and ``setup.py`` should not contain any explicit customization and therefore should not
+contain anything that could not be regenerated. In any case you should use
+version control so that you can inspect and compare changes introduced to
+``CMakeLists.txt`` and ``setup.py`` and possibly revert them. See also the next
+remark.
+
+
+But I need to manually edit and customize CMakeLists.txt and setup.py every time I run update.py!?
+--------------------------------------------------------------------------------------------------
+
+You typically never need to manually edit and customize ``CMakeLists.txt`` and
+``setup.py`` directly. You can introduce customizations in ``autocmake.cfg``
+which get assembled into the front-end scripts.
+
+
+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 overwritten at some point.
+A good solution for this is to list your sources and targets in ``src/CMakeLists.txt``
+and include the latter in ``autocmake.cfg`` using::
+
+  [src]
+  source: https://github.com/scisoft/autocmake/raw/master/modules/src.cmake
+
+If you really don't 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

doc/developers/new-project.rst

@@ -0,0 +1,61 @@
+
+
+Building a new project
+======================
+
+
+Bootstrapping Autocmake
+-----------------------
+
+Download the ``update.py`` and execute it to fetch other infrastructure files
+which will be needed to build the project (on Windows ``wget`` is probably
+not available - in this case use an alternative)::
+
+  mkdir cmake  # does not have to be called "cmake" - take the name you prefer
+  cd cmake
+  wget https://github.com/scisoft/autocmake/raw/master/update.py
+  python update.py --self
+
+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
+      lib/
+          config.py  # no need to edit
+          docopt.py  # no need to edit
+
+Note that all other listed files are overwritten (use version control!).
+
+
+Generating the CMake infrastructure
+-----------------------------------
+
+Edit ``autocmake.cfg`` and then run the ``update.py`` script which
+creates ``CMakeLists.txt`` and ``setup.py`` in the build path::
+
+  python update.py ..
+
+The script also downloads remote CMake modules specified in ``autocmake.cfg`` to a directory
+called ``downloaded/``::
+
+  cmake/
+      update.py
+      autocmake.cfg
+      lib/
+          config.py
+          docopt.py
+          downloaded/  # contains CMake modules fetched from the web
+
+
+Building the project
+--------------------
+
+Now you have ``CMakeLists.txt`` and ``setup.py`` in the project root and you can build
+the project::
+
+  cd ..
+  python setup.py [-h]
+  cd build
+  make

doc/developers/updating-modules.rst

@@ -0,0 +1,30 @@
+
+
+Updating CMake modules
+======================
+
+To update CMake modules fetched from the web you need to run the ``update.py`` script::
+
+  cd cmake
+  python update.py ..
+
+The CMake modules are not fetched or updated at configure time or build time.
+In other words, if you never re-run ``update.py`` script and never modify the
+CMake module files, then the CMake modules will remain forever frozen.
+
+
+How to pin CMake modules to a certain version
+---------------------------------------------
+
+Sometimes you may want to avoid using the latest version of a CMake module and
+rather fetch an older version with the hash ``abcd123``. To achieve this, instead
+of::
+
+  [coverage]
+  source: https://github.com/scisoft/autocmake/raw/master/modules/code_coverage.cmake
+
+pin the version to ``abcd123`` (you do not need to specify the full Git hash, a unique
+beginning will do)::
+
+  [coverage]
+  source: https://github.com/scisoft/autocmake/raw/abcd123/modules/code_coverage.cmake