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. Use automodule 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 and branch. For example:

    - Linking :issue:`1`.
    - Linking :commit:`a78ac7eb7332`.
    - Linking :branch:`docs`.
    

    It becomes:

Table Of Contents

Previous topic

sider.ext.wsgi_referer_stat — Collecting referers using sorted sets

Next topic

To do list

This Page