From 7c52934091bc0fda40d3ee034f6f0f81aeae4312 Mon Sep 17 00:00:00 2001 From: Radovan Bast Date: Mon, 27 Jul 2015 20:29:48 +0200 Subject: [PATCH] extend doc --- doc/contributors/doc.rst | 2 ++ doc/developers/configuration.rst | 9 ++++++ doc/developers/customizing-modules.rst | 6 ++-- doc/developers/faq.rst | 4 +-- doc/developers/new-project.rst | 40 ++++++++++++++------------ doc/developers/updating-modules.rst | 4 +-- doc/index.rst | 1 + doc/users/faq.rst | 14 +++++++-- 8 files changed, 52 insertions(+), 28 deletions(-) create mode 100644 doc/developers/configuration.rst diff --git a/doc/contributors/doc.rst b/doc/contributors/doc.rst index bf243b0..d846dd2 100644 --- a/doc/contributors/doc.rst +++ b/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 diff --git a/doc/developers/configuration.rst b/doc/developers/configuration.rst new file mode 100644 index 0000000..506862c --- /dev/null +++ b/doc/developers/configuration.rst @@ -0,0 +1,9 @@ + +.. _autocmake_cfg: + +Configuring autocmake.cfg +========================= + +.. todo:: + + Write me ... diff --git a/doc/developers/customizing-modules.rst b/doc/developers/customizing-modules.rst index a84e064..41ff332 100644 --- a/doc/developers/customizing-modules.rst +++ b/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 diff --git a/doc/developers/faq.rst b/doc/developers/faq.rst index 180be52..16da5e0 100644 --- a/doc/developers/faq.rst +++ b/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? diff --git a/doc/developers/new-project.rst b/doc/developers/new-project.rst index 2637b0a..ac8761e 100644 --- a/doc/developers/new-project.rst +++ b/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 diff --git a/doc/developers/updating-modules.rst b/doc/developers/updating-modules.rst index ccae289..2fe446c 100644 --- a/doc/developers/updating-modules.rst +++ b/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 diff --git a/doc/index.rst b/doc/index.rst index ea8fcac..35cc738 100644 --- a/doc/index.rst +++ b/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 diff --git a/doc/users/faq.rst b/doc/users/faq.rst index 9031864..5b992ec 100644 --- a/doc/users/faq.rst +++ b/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?