# 3.3. Documentation¶

Documentation renders the skin of software development. Every creature needs skin, so does software. In this session, we are going to learn how to use Sphinx to write documents.

Sphinx is a general-purpose documenting system, and provides many useful features for documenting computer programs.

To install Sphinx in Debian, execute the following command:

## 3.3.3. Build the Document Project to HTML¶

The document project is now ready to be build. Run:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 $make -C sphinx_guide/ html make: Entering directory /home/yungyuc/work/writing/pyengr/examples/sphinx/stage0/sphinx_guide' sphinx-build -b html -d build/doctrees source build/html Making output directory... Running Sphinx v1.1.3 loading pickled environment... not yet created building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index writing additional files... genindex search copying static files... done dumping search index... done dumping object inventory... done build succeeded. Build finished. The HTML pages are in build/html. make: Leaving directory /home/yungyuc/work/writing/pyengr/examples/sphinx/stage0/sphinx_guide'  Our document is now built and placed at sphinx_guide/build/html: $ chrome sphinx_guide/build/html/index.html


## 3.3.4. reStructuredText¶

reStructuredText (usually short-handed as “reST” or “rst”) is the fundamental language that Sphinx uses for composition. The syntax of rst is designed to extend, and Sphinx uses the syntax to support a wide range of contents.

As a beginner you can start with reading the index.rst generated by sphinx-quickstart. It locates at sphinx_guide/source/index.rst:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 .. Sphinx Guide documentation master file, created by sphinx-quickstart on Sun Jul 14 14:06:36 2013. You can adapt this file completely to your liking, but it should at least contain the root toctree directive. Welcome to Sphinx Guide's documentation! ======================================== Contents: .. toctree:: :maxdepth: 2 python math Indices and tables ================== * :ref:genindex * :ref:modindex * :ref:search 

We won’t have enough time to cover everything in rst. In the following sections we will demonstrate some important features of the format. You can check reStructuredText primer (at Sphinx) and reStructuredText (at docutils) for detailed description.

Before start, we will create placeholders for the materials to be added. Let’s insert the following at the 14th line of index.rst (at the same indentation level of :maxdepth: 2):

python
math


Also, we create the corresponding files in sphinx_guide/source directory:

$touch python.rst math.rst  If you rebuild the document now (note, you must build the document in the directory sphinx_guide or the Makefile will be missing), you will find no change in HTML. It’s normal. ## 3.3.5. Documenting Python¶ Sphinx extends rst to let us use directives for documenting computer programs. However, by default Sphinx wants to you to write documents outside the source code, and this is what we are going to do now. Edit the file sphinx_guide/source/python.rst and put in the following text:   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 =============== Python Examples =============== .. py:function:: one_python_function(arg1, arg2) This is to demonstrate how to document a Python function with Sphinx. *arg1* and *arg2* are the positional arguments of the function. .. py:class:: DemonstrativeClass This is a Python class. .. py:method:: clone_myself(param) This is an instance method of :py:class:DemonstrativeClass. Assume the only argument *param* is a :py:class:str. The method returns another :py:class:DemonstrativeClass object. .. py:attribute:: settable_value This is an instance attribute. Assume it (:py:attr:settable_value) is used by :py:meth:clone_myself.  In the above example we used the Python domain in Sphinx. You can build the document and get the results (click the newly built Python Examples in the index page): We used the following directives: .. py:function:: name(signature) See http://sphinx-doc.org/domains.html#directive-py:function. This directive allows us to document a Python function. .. py:class:: name[(signature)] See http://sphinx-doc.org/domains.html#directive-py:class. This directive allows us to document a Python class. We can put other directives like py:class inside it. .. py:method:: name(signature) See http://sphinx-doc.org/domains.html#directive-py:method. This directive allows us to document an instance method. .. py:attribute:: name See http://sphinx-doc.org/domains.html#directive-py:attribute. This directive allows use to document an instance attribute. We also used the following roles to refer to Python objects: :py:class: See http://sphinx-doc.org/domains.html#role-py:class. It refers to a Python class. :py:attr: See http://sphinx-doc.org/domains.html#role-py:attr. It refers to a Python attribute. :py:meth: See http://sphinx-doc.org/domains.html#role-py:meth. It refers to a Python method. This section is a simple introduction to documenting Python code. To write good documents, you need to familiarize yourself with the vocabulary in the Sphinx Python domain. ## 3.3.6. Mathematical Formula¶ Another plausible feature of Sphinx is the ability to connect to LaTeX for mathematical formula. To use this feature we need to install TeXLive: $ sudo apt-get install texlive


When configuring our test project we’ve enabled the pngmath extension. Simple put the following text in math.rst:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 ==================== Mathematical Formula ==================== This is one of my favoriate formula (one-dimensional, first-order hyperbolic partial differential equation): .. math:: :label: e:onedim \frac{\partial u}{\partial t} + \frac{\partial f(u)}{\partial x} = 0 We can write virtually any mathematical expresions, like an integral: .. math:: :label: e:integral F(\omega) \cong \frac{\Delta x}{2}\left[ g(0) + 2\sum_{n=1}^{N-2}g(x_n) + g(A) \right] or a matrix: .. math:: :label: e:matrix A = \left[\begin{array}{ccc} a_{11} & a_{12} & a_{13} \\ a_{21} & a_{22} & a_{23} \\ a_{31} & a_{32} & a_{33} \end{array}\right] All of Eqs. :eq:e:onedim, :eq:e:integral, and :eq:e:matrix can be numbered and referred. Inline mathematics like :math:e = \sum_{n=0}^{\infty} \frac{1}{n!} also works. 

The directive and role involved are:

.. math:: 
:math:

After building the document, you can get the results by clicking the Mathematical Formula in the index page:

## 3.3.7. Using Third-Party Extensions (Optional)¶

There are a lot of extensions available to Sphinx. Some of them are organized in https://bitbucket.org/birkenfeld/sphinx-contrib/. Here I am demonstrate how to enable the third-party extension by using sphinx-issuetracker.

sudo apt-get install python-sphinx-issuetracker


For this example we will use pyengr. You need to clone it to your local computer. Right after the extension list of conf.py, add:

try:
from sphinxcontrib import issuetracker
except ImportError:
pass
else:
extensions.append('sphinxcontrib.issuetracker')


Then add the configuration to the extension:

# issuetracker settings.
issuetracker = 'bitbucket'
issuetracker_project = 'yungyuc/pyengr'


After the settings, we can use #1 or #2` to refer to the issues on bitbucket, like: #1 and #2.