From 7c5ce060e79b942bd12483d615aebaa03cb112fd Mon Sep 17 00:00:00 2001 From: Marco Biasini <marco.biasini@unibas.ch> Date: Mon, 1 Nov 2010 09:31:53 +0100 Subject: [PATCH] extend contributing document --- modules/doc/contributing.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/modules/doc/contributing.rst b/modules/doc/contributing.rst index 740359810..a69803233 100644 --- a/modules/doc/contributing.rst +++ b/modules/doc/contributing.rst @@ -38,6 +38,34 @@ Even though it is not neccessary, it is advised to carry out your changes in a s From now on, all your work will be carried out in my_branch. Make your changes and once you are happy, commit them to your repository. + +Writing Good Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Your commit message should have a one-line description that summarize the change and optionally a more detailed description of what the changes imply. An example from the commit history. The one-liner and the detailed description are separated by an empty line. The reason for this format is that the one-line description will be used as the subject line for the patches generated by format-patch and the ones sent to the commit mailing lists. People can quickly see if the change is of interest to that they can savely ignore the e-mail. + +Additionally, they also come in handy when using the --online option of ``git log``. + +Writing Documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +OpenStructure uses `sphinx <http://sphinx.pocoo.org>`_ as the documentation generator. The main part of the documentation each module resides in files with the ``.rst`` extension in a sub-folder called doc. + +To convert the .rst files to html use the doc/make.py script: + +.. code-block:: bash + + ost doc/make.py + +The script first recursively searches for modified ``.rst`` files, starting at the modules directory and copies the files that have changed to ``doc/source``. It also copies images to the source directory. Then it runs sphinx to convert the documentation to html. If no further options are given to the script, the html documentation is generated. The HTML, CSS and static media files will be put into ``doc/html/build``. + +For classes and functions written in Python, it is possible to tell sphinx to extract the documentation directly from the doc-string. For example, to get the documentation for :func:`~ost.io.LoadPDB`, you can use: + +.. code-block:: rest + + .. autofunction:: ost.io.LoadPDB + + Synchronizing with upstream changes -------------------------------------------------------------------------------- -- GitLab