diff --git a/doc/contributing.rst b/doc/contributing.rst
index ac0a15f3733e58afcf3c8aaaceeae0e9fa25343a..832af70cc2e46a71d3850967a075a8f423ece6d8 100644
--- a/doc/contributing.rst
+++ b/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)
--------------------------------------------------------------------------------
diff --git a/doc/dev_setup.rst b/doc/dev_setup.rst
index ea7f1c86cc352fab623b30a94e1d5ee4690fb8a2..3b450accf0a5cb18ada95e2e7b1ab6d0e35799dd 100644
--- a/doc/dev_setup.rst
+++ b/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|
--------------------------------------------------------------------------------