SCHWED-2641: Doc update for devs: doc/html and folder-descriptions.

doc/contributing.rst

@@ -23,7 +23,6 @@ tell you for which branch you went, a story of failure otherwise.
 
    $ git checkout develop
    Switched to branch 'develop'
-   $
 
 Sitting on top of the right code basis, you should just spawn your own branch
 from it. As an example, your feature will go by the name of 'sidechain'.
@@ -32,7 +31,6 @@ from it. As an example, your feature will go by the name of 'sidechain'.
 
    $ git checkout -b sidechain
    Switched to a new branch 'sidechain'
-   $
 
 This time, |git| should tell you about going for **a new** branch.
 
@@ -42,7 +40,6 @@ install our very own |git| hook to check some coding rules on commit.
 .. code-block:: console
 
    $ cp extras/pre_commit/pre-commit .git/hooks/
-   $
 
 With that in place, changes which break our coding standards will abort any
 commit.
@@ -55,7 +52,6 @@ list of directories which are likely to be used in every project.
    $ mkdir -p sidechain/doc
    $ mkdir -p sidechain/pymod
    $ mkdir -p sidechain/tests
-   $
 
 If you run ``git status`` at this point, you will see basically nothing. That
 is, |git| does not admire empty directories. Before you bring your module under
@@ -66,7 +62,6 @@ version control, create a couple of files which are always needed.
    $ touch sidechain/pymod/__init__.py
    $ echo ":mod:\`~promod3.sidechain\` - ProMod3 side chain optimiser" >> sidechain/doc/index.rst
    $ echo "================================================================================" >> sidechain/doc/index.rst
-   $
 
 Having an empty :file:`__init__.py` is perfectly fine for |python|, it just
 announces a directory as a module. But a blank :file:`index.rst` has the chance
@@ -82,7 +77,6 @@ extending some around the directory root.
    $ touch sidechain/CMakeLists.txt
    $ touch sidechain/pymod/CMakeLists.txt
    $ touch sidechain/doc/CMakeLists.txt
-   $
 
 Each of those files still needs a bit of content. The simplest one comes from
 the module's root, :file:`sidechain/CMakeLists.txt`:
@@ -182,7 +176,6 @@ will not show up in ``git status``.
 
    $ mkdir build
    $ cd build
-   $
 
 To actually create all the makefiles and generated files, you may use one of
 the configuration scripts from the :file:`conf-scripts` directory. Usually
@@ -255,6 +248,8 @@ Note how we listed the test data that we require in the unit test by defining
 Now tests should be available by ``make check``, ``make codetest`` and
 ``make test_reconstruct_sidechains.py_run``.
 
+.. _how-to-start-your-own-action:
+
 --------------------------------------------------------------------------------
 How To Start Your Own Action
 --------------------------------------------------------------------------------
@@ -463,6 +458,8 @@ the ``doctest`` and ``linkcheck`` targets. Alternatively you can run:
   will provide you with a target ``test_awesome_feature.py_run``. If your module
   has |C++| tests, those will be available by ``test_suite_your_module_run``.
 
+.. _writing-documentation:
+
 --------------------------------------------------------------------------------
 Writing Documentation
 --------------------------------------------------------------------------------
@@ -483,7 +480,8 @@ documentation, here is a helpful list of standard formatters:
 http://sphinx-doc.org/markup/inline.html
 
 If you write new functionality for |project|, or fix bugs, feel free to extend
-the Changelog. It will be automatically pulled into the documentation.
+the :file:`CHANGELOG` file. It will be automatically pulled into the
+documentation.
 
 It is highly recommended to add code examples with your documentation. For that
 purpose, you should write a fully runnable script, which is to be placed in the
@@ -519,6 +517,18 @@ codes for examples). A few more guidelines for example codes:
   the external dependencies are not available, output a warning and skip the
   test.
 
+A copy of the generated html documentation is kept in :file:`doc/html` so that
+there is no need to compile |project| to read it. Our policy is to keep that
+folder in-sync with the latest documentation at least on the ``master`` branch
+(i.e. for every release). You can use the following commands to do the update:
+
+.. code-block:: console
+
+   $ cd <PROMOD3_PATH>/build
+   $ make html
+   $ rsync -iv -az --exclude=".*" --delete \
+           "stage/share/promod3/html/" "../doc/html"
+
 --------------------------------------------------------------------------------
 Third Party Contributions (License Issues)
 --------------------------------------------------------------------------------

doc/dev_setup.rst

@@ -168,18 +168,18 @@ repository root. The directory structure of your module should look like this:
 .. code-block:: text
 
    promod3.git/                            Project folder
-         your_module/                      Directory housing your project
-               CMakeLists.txt              CMake configuration for this module
+         your_module/                      Module directory
+               CMakeLists.txt              CMake configuration
                data/                       Extra data (if needed)
                      CMakeLists.txt        CMake configuration
                      ...
                doc/                        Documentation
                      CMakeLists.txt        CMake configuration
-                     your_module.rst       Overview/ frame of your module
+                     your_module.rst       Overview/frame of your module
                      ...
                pymod/                      Python code
                      CMakeLists.txt        CMake configuration
-                     __init__.py           Init file needed for importing
+                     __init__.py           Init file needed for import
                      submodule1.py         Code
                      ...
                src/                        C/ C++ code
@@ -195,6 +195,20 @@ repository root. The directory structure of your module should look like this:
                      test_submodule1.py    Unit tests for submodule1
                      ...
 
+Additionally to the module directories there are a few extra folders:
+
+- :file:`actions`: Scripts callable as ``pm <ACTION_NAME>``.
+  See :ref:`here <how-to-start-your-own-action>` for details.
+- :file:`cmake_support`: Helper functions for |cmake|.
+  See :ref:`here <pm3-cmake-doc>` for details.
+- :file:`doc`: High-level documentation, test scripts (:file:`doc/tests`) and a
+  copy of the generated html documentation (:file:`doc/html`). The latter must
+  be kept up-to-date at least on the ``master`` branch.
+  See :ref:`here <writing-documentation>` for details.
+- :file:`extras`: Extra data and information that doesn't fit anywhere
+  else (e.g. |git| hooks or scripts to recreate the binary files).
+- :file:`scripts`: Input for scripts that end up in :file:`stage/bin`
+
 --------------------------------------------------------------------------------
 |cmake|
 --------------------------------------------------------------------------------