Documentation guides¶
This project use Sphinx for documentation and Read the Docs for documentation hosting. Build the documentation always before you commit — You must not miss documentation of your contributed code.
Be fluent in reStructuredText.
Build¶
Install Sphinx 1.1 or higher first. If it’s been installed already, skip this.
$ easy_install "Sphinx>=1.1"
Use make in the docs/
directory.
$ cd docs/
$ make html
You can find the built documentation in the docs/_build/html/
directory.
$ python -m webbrowser docs/_build/html/ # in the root
Convention¶
Follow styles as it was.
Every module/package has to start with docstring like this:
""":mod:`sider.modulename` --- Module title ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Short description about the module. """
and make reStructuredText file of the same name in the
docs/sider/
directory. Useautomodule
directive.All published modules, constants, functions, classes, methods and attributes (properties) have to be documented in their docstrings.
Source code to quote is in Python, use a literal block. If the code is a Python interactive console session, don’t use it (see below).
The source code is not in Python, use a
sourcecode
directive provided by Sphinx. For example, if the code is a Python interactive console session:.. sourcecode:: pycon >>> 1 + 1 2
See also the list of Pygments lexers.
Link Redis commands using
redis
role. For example:It may send :redis:`RPUSH` multiple times.
Tips¶
You can link Redis commands through
redis
role. For example:Linking :redis:`ZRANGEBYSCORE` command.
You can link
issue
,commit
andbranch
. For example:- Linking :issue:`1`. - Linking :commit:`a78ac7eb7332`. - Linking :branch:`docs`.
It becomes:
- Linking issue #1.
- Linking a78ac7eb7332.
- Linking docs.