extend doc

doc/contributors/doc.rst

@@ -3,6 +3,8 @@
 Contributing to the documentation
 =================================
 
+Contributions and patches to the documentation are most welcome.
+
 This documentation is refreshed upon each push to the central repository.
 
 The module reference documentation is generated from the module sources using

doc/developers/configuration.rst

@@ -0,0 +1,9 @@
+
+.. _autocmake_cfg:
+
+Configuring autocmake.cfg
+=========================
+
+.. todo::
+
+   Write me ...

doc/developers/customizing-modules.rst

@@ -21,9 +21,9 @@ 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.
+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.
 
 
 Create own CMake modules

doc/developers/faq.rst

@@ -1,7 +1,7 @@
 
 
-FAQ
-===
+FAQ for developers
+==================
 
 
 Should I include and track also files generated by Autocmake in my repository?

doc/developers/new-project.rst

@@ -1,20 +1,20 @@
 
 
-Building a new project
-======================
+Creating the configuration for 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)::
+Download the ``update.py`` and execute it with ``--self`` 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
+  $ 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)::
@@ -32,12 +32,14 @@ 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::
+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``::
 
-  python update.py ..
+  $ python update.py ..
 
-The script also downloads remote CMake modules specified in ``autocmake.cfg`` to a directory
+The script also downloads external CMake modules specified in ``autocmake.cfg`` to a directory
 called ``downloaded/``::
 
   cmake/
@@ -52,10 +54,10 @@ called ``downloaded/``::
 Building the project
 --------------------
 
-Now you have ``CMakeLists.txt`` and ``setup.py`` in the project root and you can build
-the project::
+Now you have ``CMakeLists.txt`` and ``setup.py`` in the project root and the project
+can be built::
 
-  cd ..
-  python setup.py [-h]
-  cd build
-  make
+  $ cd ..
+  $ python setup.py [-h]
+  $ cd build
+  $ make

doc/developers/updating-modules.rst

@@ -5,8 +5,8 @@ Updating CMake modules
 
 To update CMake modules fetched from the web you need to run the ``update.py`` script::
 
-  cd cmake
-  python update.py ..
+  $ 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

doc/index.rst

@@ -21,6 +21,7 @@ For developers who use Autocmake
 
    developers/faq.rst
    developers/new-project.rst
+   developers/configuration.rst
    developers/customizing-modules.rst
    developers/updating-modules.rst
 

doc/users/faq.rst

@@ -1,7 +1,17 @@
 
 
-FAQ
-===
+FAQ for users
+=============
+
+
+TLDR How do I compile the code?
+-------------------------------
+
+::
+
+  $ python setup.py [-h]
+  $ cd build
+  $ make
 
 
 How can I specify the compiler?