Skip to content

Producing documentation

Jump to bottom
QLutz edited this page Oct 1, 2020 · 7 revisions

Documentation overview

The documentation written in scikit-network can be roughly divided into three parts:

  • docstrings for the code which define the expected inputs, outputs and behaviours of each object
  • tutorials aimed at providing users with examples of how to use the package
  • reStructuredText (RST) files which define how the final documentation is structured

The documentation is generated using Sphinx with the ReadTheDocs theme and nbsphinx for the tutorials.

Docstrings

Docstrings are written in the Python files themselves, following Numpy docstring guidelines.

labels: np.ndarray

  • The description of each function or class should begin with a verb (imperative form) or a noun.

Cluster nodes of the graph.

  • The description of each function or class should include an example, in the following form:

imports
algo
data
output

  • Reference style: APA

Blondel, V. D., Guillaume, J. L., Lambiotte, R., & Lefebvre, E. (2008). Fast unfolding of communities in large networks. Journal of statistical mechanics: theory and experiment.

Tutorials

Tutorials are Jupyter notebooks. Before pushing any changes to a tutorial make sure you made actual changes to it (merely running the notebook might trigger Git to stage it) and that you left no blank cell at the end of the file.

Note: As per the .gitignore file, notebooks that are in a subdirectory of the docs/tutorials folder are the only ones that are taken into account by Git. You can use Jupyter notebooks elsewhere in the project folder for other purposes.

RST files

RST files define what is included in the final documentation. In particular:

  • .. automodule:: sknetwork.submodule, .. autoclass:: sknetwork.submodule.Class (with :members: keyword) and .. autofunction:: sknetwork.submodule.function are used to include docstrings in an RST file

  • the name of a notebook is used in a .. toctree:: to include it in the tutorials

  • non-index RST files should, in turn, be included in an index

Building the docs

To build the docs from PyCharm see François Durand's package. Additionally, PanDoc is required.

Additionally, you might add the -E flag in the options field of your configuration to have PyCharm clean (i.e. remove previous builds) the docs before a new build is started. This prevents issues with toctrees updates.

Tips

Should you want to make a table in rST files, we recommend using a table generator (such as this one) as making them manually can be quite a hassle.

Clone this wiki locally