From c669bd10e10b45d9124fdc9b036929bd8ea6dba2 Mon Sep 17 00:00:00 2001
From: Radovan Bast <bast@users.noreply.github.com>
Date: Fri, 31 Jul 2015 12:35:54 +0200
Subject: [PATCH] more doc

---
 doc/developers/configuration.rst | 65 ++++++++++++++++++++++++++++++--
 doc/developers/example.rst       |  2 +-
 2 files changed, 62 insertions(+), 5 deletions(-)

diff --git a/doc/developers/configuration.rst b/doc/developers/configuration.rst
index 973403d..911e0a3 100644
--- a/doc/developers/configuration.rst
+++ b/doc/developers/configuration.rst
@@ -53,10 +53,10 @@ The only section where the name matters is ``[project]``::
   [project]
   name: numgrid
 
-This is where we define the project name (here "numgrid"). Every project needs
-at least this section and this section has to be called "project".
+This is where we define the project name (here "numgrid"). This section has to
+be there and it has to be called "project" (but it does not have to be on top).
 
-The names of the other sections do not matter to Autocmake. You can name them like this::
+The names of the other sections do not matter to Autocmake. You could name them like this::
 
   [project]
   name: numgrid
@@ -70,12 +70,69 @@ The names of the other sections do not matter to Autocmake. You can name them li
   [whatever]
   source: https://github.com/scisoft/autocmake/raw/master/modules/cxx.cmake
 
-But it is much better to choose names that are meaningful to you.
+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::
+
+  [project]
+  name: minime
+
+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
+
+Good. Now we can generate ``CMakeLists.txt`` and ``setup.py``::
+
+  $ python update ..
+
+Here is the generated ``CMakeLists.txt``::
+
+  # set minimum cmake version
+  cmake_minimum_required(VERSION 2.8 FATAL_ERROR)
+
+  # project name
+  project(minime)
+
+  # do not rebuild if rules (compiler flags) change
+  set(CMAKE_SKIP_RULE_DEPENDENCY TRUE)
+
+  # if CMAKE_BUILD_TYPE undefined, we set it to Debug
+  if(NOT CMAKE_BUILD_TYPE)
+      set(CMAKE_BUILD_TYPE "Debug")
+  endif()
+
+This is the very minimum. Every project will have at least these settings.
+
+And we also got a ``setup.py`` script with the following default options::
+
+  $ python setup.py -h
+
+  Usage:
+    ./setup.py [options] [<builddir>]
+    ./setup.py (-h | --help)
+
+  Options:
+    --type=<TYPE>              Set the CMake build type (debug, release, or relwithdeb) [default: release].
+    --generator=<STRING>       Set the CMake build system generator [default: Unix Makefiles].
+    --show                     Show CMake command and exit.
+    --cmake-options=<OPTIONS>  Define options to CMake [default: None].
+    <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, no nothing. We need to flesh out
+``CMakeLists.txt`` and this is what we will do in the next section.
+
+
 Assembling CMake plugins
 ------------------------
 
diff --git a/doc/developers/example.rst b/doc/developers/example.rst
index 4edacc8..50fbcf4 100644
--- a/doc/developers/example.rst
+++ b/doc/developers/example.rst
@@ -1,6 +1,6 @@
 
 
-Example hello world project
+Example Hello World project
 ===========================
 
 Write me ...