Writing Documentation for PyPhysim¶
The handwritten rst files should be listed in the toctree in the
List of Documentation Articles section of the index.rst
file, while the
documentation for each package is automatically generated using
sphinx-apidoc
and should be listed in the toctree in the
description.rst
file.
In order to generate the rst files for each package with sphinx-apidoc
call
the command sphinx-apidoc -o docs pyphysim
from outside the docs folder.
Note that sphinx-apidoc
will generate a corresponding .rst file for each
package, that uses the autodoc feature of sphinx to include the docstrings of
the python files in the actual documentation. For instance, the .rst
file of
the comm
module (whose name is pyphysim.comm.rst
) is shown below.
pyphysim.comm package
=====================
Submodules
----------
pyphysim.comm.blockdiagonalization module
-----------------------------------------
.. automodule:: pyphysim.comm.blockdiagonalization
:members:
:undoc-members:
:show-inheritance:
pyphysim.comm.waterfilling module
---------------------------------
.. automodule:: pyphysim.comm.waterfilling
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: pyphysim.comm
:members:
:undoc-members:
:show-inheritance:
Notice the use of “.. automodule::
” to get the documentation of the comm
package modules from the source code.
Therefore, you only need to run sphinx-apidoc
when new modules are created
in PyPhysim. Everything else will be automatically done by sphinx with the help
of the autodoc extension.
Writing math in the documentation¶
The sphinx documentation generation system is configured to allow the
inclusion of math snippets with LaTeX syntax in the documentation. Simply
put a directive like :math:`x+y = \frac{1}{2}`
in the documentation and it will be rendered as \(x+y = \frac{1}{2}\)
in the final HTML documentation.
In order for this to work you need to download MathJax from http://www.mathjax.org/download/ and put it in the docs/Mathjax/ folder.
Also, in order to make writing math easier, a few extra LaTeX macros should
be defined. In special, we use bold to indicate matrices. Usually one would
need to write :math:`\mathbf{H}_{jk}`
to write \(\mathbf{H}_{jk}\),
but the macro “\mtH
” is used instead for a bold “H” such that we can
write the same think with :math:`\mtH_{jk}`
and this should be
configured in Mathjax. Likewise, equivalent macros must also be defined for
the other letters as well as \vtH
and similar to represent vectors
(lower case bold letters).
The after downloading Mathjax to the docs/Mathjax/ edit the docs/Mathjax/config/local/local.js file and add the following macros there.
// Matrices
TEX.Macro("mtA", "\\mathbf{A}");
TEX.Macro("mtB", "\\mathbf{B}");
TEX.Macro("mtC", "\\mathbf{C}");
TEX.Macro("mtD", "\\mathbf{D}");
TEX.Macro("mtE", "\\mathbf{E}");
TEX.Macro("mtF", "\\mathbf{F}");
TEX.Macro("mtG", "\\mathbf{G}");
TEX.Macro("mtH", "\\mathbf{H}");
TEX.Macro("mtI", "\\mathbf{I}");
TEX.Macro("mtJ", "\\mathbf{J}");
TEX.Macro("mtK", "\\mathbf{K}");
TEX.Macro("mtL", "\\mathbf{L}");
TEX.Macro("mtM", "\\mathbf{M}");
TEX.Macro("mtN", "\\mathbf{N}");
TEX.Macro("mtO", "\\mathbf{P}");
TEX.Macro("mtP", "\\mathbf{P}");
TEX.Macro("mtQ", "\\mathbf{Q}");
TEX.Macro("mtR", "\\mathbf{R}");
TEX.Macro("mtS", "\\mathbf{S}");
TEX.Macro("mtT", "\\mathbf{T}");
TEX.Macro("mtU", "\\mathbf{U}");
TEX.Macro("mtV", "\\mathbf{V}");
TEX.Macro("mtW", "\\mathbf{W}");
TEX.Macro("mtX", "\\mathbf{X}");
TEX.Macro("mtY", "\\mathbf{Y}");
TEX.Macro("mtZ", "\\mathbf{Z}");
// Vectors
TEX.Macro("vtB", "\\mathbf{b}");
TEX.Macro("vtC", "\\mathbf{c}");
TEX.Macro("vtD", "\\mathbf{d}");
TEX.Macro("vtE", "\\mathbf{e}");
TEX.Macro("vtF", "\\mathbf{f}");
TEX.Macro("vtG", "\\mathbf{g}");
TEX.Macro("vtH", "\\mathbf{h}");
TEX.Macro("vtI", "\\mathbf{i}");
TEX.Macro("vtJ", "\\mathbf{j}");
TEX.Macro("vtK", "\\mathbf{k}");
TEX.Macro("vtL", "\\mathbf{l}");
TEX.Macro("vtM", "\\mathbf{m}");
TEX.Macro("vtN", "\\mathbf{n}");
TEX.Macro("vtO", "\\mathbf{p}");
TEX.Macro("vtP", "\\mathbf{p}");
TEX.Macro("vtQ", "\\mathbf{q}");
TEX.Macro("vtR", "\\mathbf{r}");
TEX.Macro("vtS", "\\mathbf{s}");
TEX.Macro("vtT", "\\mathbf{t}");
TEX.Macro("vtU", "\\mathbf{u}");
TEX.Macro("vtV", "\\mathbf{v}");
TEX.Macro("vtW", "\\mathbf{w}");
TEX.Macro("vtX", "\\mathbf{x}");
TEX.Macro("vtY", "\\mathbf{y}");
TEX.Macro("vtZ", "\\mathbf{z}");