Documentation

All the documentation is available in the packetweaver/doc folder. Written in ReStructuredText, you may build it locally using Sphinx.

If you wish to contribute to the documentation, either by editing the Python docstring in the source code or the documentation pages themselves, this a convenient way to visualize what your modifications will look like.

Documentation toolset installation

To install the documentation toolset, you may run the following commands:

# pip3 install sphinx pylint
# apt install graphviz

Sphinx is the main library that builds the documentation, and pylint is used for its library pyreverse that draw UML graphs from Python source code. Graphviz is installed to give pyreverse access to the png export format.

If you want to use the ReadTheDocs theme, you may install it using:

pip3 install sphinx_rtd_theme

It will be automatically used by the Sphinx configuration file conf.py.

The different actions to build the documentation are part of the Sphinx Makefile.

To use it, you may browse to the documentation folder (cd packetweaver/doc/) and use one of the make <target> commands.

Warning

As some Makefile targets use relative paths, please always use it while being in the same directory.

Building the API documentation

Sphinx apidoc is used to build a documentation of the source code files using their docstring content. To generate the corresponding RestructuredText documentation files, you may run:

make apidoc

It will automatically delete the previous built file and generate new ones from scratch.

Building the complete documentation

To build only the basic documentation content and view it with your default web browser, you may use:

make html
make show

html is a Sphinx target that specifies an output format. You may use other options such as the single page html version of it with:

make singlehtml
xdg-open build/singlehtml/index.html

Building UML diagrams

You may build a UML representation of PacketWeaver core module using pyreverse. Similarly, the Makefile target is:

make uml-core
xdg-open build/classes_pw_core.png
xdg-open build/packages_pw_core.png

Building and cleaning everything

Finally, the all target performs all the previous tasks:

make clean
make all
make show

The clean target will clear everything except the files generated by the apidoc target, which lives in the source/ folder. To fully clean the doc/ folder, you could run:

make clean
rm source/apidoc/*