Contributing to the documentation¶
This document presents documentation conventions and tools.
This documentation uses Python-sphinx [1]. It uses reStructuredText [2] syntax.
Conventions¶
Language¶
The documentation is written in english.
Line length¶
Limit all lines to a maximum of 79 characters whenever possible. Exceptions can be long URL or some literal blocks.
Headings¶
Follow the Sphinx’s recommendation about sections [3].
As an example:
##################
H1: document title
##################
*********
Sample H2
*********
Sample H3
=========
Sample H4
---------
And sample text.
If you need more than H4, then consider creating a new document.
Code blocks¶
Use the code-block directive and explicitely specify the programming language.
As an example:
.. code-block:: python
import this
Links and references¶
On pages which are quite long, use links and references footnotes with the “target-notes” directive. As an example:
#############
Some document
#############
Some text which includes links to `Example website`_ and many other links.
`Example website`_ can be referenced multiple times.
(... document content...)
And at the end of the document...
**********
References
**********
.. target-notes::
.. _`Example website`: http://www.example.com/
This Contributing to the documentation page uses this syntax.
Install Sphinx¶
Python-sphinx [1] installation is covered in Install a development environment.
In other cases, please refer to Python-sphinx [1] documentation.
Export documentation to HTML¶
Go to docs/ folder in Thumbnailer project and use the provided Makefile:
cd docs/
make html
cd ..
HTML documentation is exported to docs/_build/html/.
Doctests¶
This documentation uses the Sphinx’s doctest extension [4].
Write doctests¶
Here is a RST code sample to write doctests.
.. doctest::
>>> print "Hello world!"
Hello world!
See Sphinx’s doctest extension [4] and Python’s doctest [5] documentations for details.
Run doctests¶
Go to docs/ folder in Thumbnailer project and use the provided Makefile:
cd docs/
make doctests
cd ..