more doc

doc/about.rst

@@ -0,0 +1,41 @@
+
+
+About Autocmake
+===============
+
+CMake typically generates Makefiles based on CMakeLists.txt files. Autocmake
+generates and assembles CMake files based on lightweight cfg-files.
+
+
+CMake cons
+----------
+
+- Complexity
+- Yet another thing to learn: requires learning and training
+- Typically many files instead of one file
+- Documentation ("Which file do I need to edit to achieve X?")
+
+
+CMake pros
+----------
+
+- Makes it possible and relatively easy to download, configure, build, install, and link external modules
+- Cross-platform system- and library-discovery
+- CTest uses a Makefile (possible to run tests with -jN)
+
+
+Motivation to create a CMake framework library
+----------------------------------------------
+
+- Simplify CMake code transfer (scientific projects typically have very similar requirements)
+    - FC, CC, CXX
+    - Compiler flags
+    - Front-end script (setup.py)
+    - MPI, OMP, CUDA
+    - Math libraries
+- Make it easy for people who know CMake well to create well defined configurations
+- Make it easy for people who do not know CMake to get started in minutes
+- Philosophy
+    - Explicit is better than implicit
+    - Convention over configuration
+- Well documented set of plug-ins

doc/bootstrap.rst

@@ -21,5 +21,4 @@ not overwritten by the script)::
       ├── config.py  # no need to edit
       └── docopt.py  # no need to edit
 
-If you use version control, then now is a good moment to status/diff/add
+Note that all other listed files are overwritten (use version control!).
-the newly created files.

doc/customization.rst

@@ -3,10 +3,36 @@
 Customizing the CMake modules
 =============================
 
+You have at least four options to customize CMake modules:
+
+
+Directly inside the generated modules directory
+-----------------------------------------------
+
 The CMake modules can be customized directly inside ``modules/`` but this is
-not very convenient as the customizations may be overwritten by the
+the least elegant solution since the customizations may be overwritten by the
 ``boostrap.py`` script.
 
+
+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``.
+
+
+Create own CMake modules
+------------------------
+
+Of course you can also create own modules and source them in ``autocmake.cfg``.
+Sometimes you have to.
+
+
+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 of course also strive for generality and portability.

doc/index.rst

@@ -6,6 +6,7 @@ Autocmake
 .. toctree::
    :maxdepth: 2
 
+   about.rst
    bootstrap.rst
    cmakelists.rst
    customization.rst