Contributing

Further details coming eventually.

Guidelines and Conventions

Further details coming eventually.

Docstring style

The docstring style used throughout the DESDEO framework follows the style dictated by Google.

Software development

Further details coming eventually.

How to get started

Further details coming eventually.

Project management tools

Further details coming eventually.

Software development tools

Further details coming eventually.

Documentation

Introduction

To build the documentation for the DESDEO framework and its various modules, Sphinx is used. Sphinx offers excellent utilities for automatically generating API documentation based on existing documentation located in source code, and for adding custom content.

Automatically generated documentation and custom content is specified as reStructuredText. ReStructuredText is a markup language just like Markdown or html, but offers the possibility to extend the language for specific domains. The file extention .rst is used for files containing reStructuredText content. Sphinx can then be used to generate documentation in various formats, such as html and pdf, based on content provided as reStructuredText.

Resources to get started with Sphinx

The official documentation offers a good guide for getting started. It is advised to read through the guide before contributing to the documentation. After reading the guide, the reader is encouraged to check out the contents of the source file used to generate the current page. The source file can be accessed by going to the top of this page and following the Edit on GitHub-link. It is also advised to check out the content of the docs file found in the main repository of the DESDEO framework. After checking the source file used to generate this page, the user should be familiar with at least basic sectioning, hyperlinks, code blocks, note blocks, and lists.

Other useful resources include:

  • Official documentation for reStructuredText.

  • ReStructuredText syntax cheatsheet.

  • A conference talk about Sphinx given during PyCon 2018. (YouTube has also many other videos on Sphinx as well)

  • A more through tutorial written by the matplotlib developers on how to achieve a documentation similar to theirs.

Extensions

In the DESDEO framework, some Sphinx extensions are used to faciliate automatic documentation generation. At least the following extensions are used:

Included in Sphinx:

User provided extensions:

Building and testing the documentation

If Sphinx has been setup following the official quick guide, the documentation can be build by running the commnad

make html

in the root direcotry containing the documentation. This will produce documentation in an html format residing in the _build folder in the documentation’s root directory. To view the documentation built, use any web browser. For example, with Firefox, this is achieved by issuing the command

firefox _build/html/index.html

Note

The directory _build generated by sphinx-quickstart should not be under version control.

Deployment

Note

Most of the content in this section is relevant only when setting up the documentation for the first time for a module.

The documentation for each of the DESDEO modules is hosted on readthedocs.org. For the documentation to be build correctly, a YAML congiguration file named .readthedocs.yml should be present in the root directory of the project (not the root directory of the documentation!) A minimal configarion file could look like this:

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
Sphinx:
configuration: docs/conf.py

# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
    - requirements: docs/requirements.txt

Especially the locations of the configuration files docs/conf.py and docs/requirements.txt are important to enable readthedocs to correctly build the documentation.

Note

The requirements file should contain the requirements for building the documentation. It does not necessarely need to contain all the requirements of the module the documentation is being build for. However, for building the documentation for some of the modules, like desdeo-mcdm for example, the whole module needs to be installed for Sphinx to be able to compile the documentation. In that case, having the project’s whole requirements in the requirements file pointed at in .readthedocs.yml is justified.

If a requirements.txt if required, but poetry is used to manage dependencies, then the command

poetry export --dev -f requirements.txt > requirements.txt

can be used to generate a requirements file.

For more configuration options, go here. The whole documentation for readthedocs can be found here.

Caveats

Some common caveats with Sphinx:

  • The intendation Sphinx expects in the reStructuredText files is three spaces to specify the scope of the options and content of a directive. Options should follow the directive immediately on the following line, one option per line, and the content should be separated by one blank line from the options (if no options are provided, the blank line should be between the directive and the contents). For example, the following is correct:

    .. toctree::
       :maxdepht: 2
    
       content
       morecontent
    

    The following, however, is incorrect:

    .. toctree::
       :maxdepht: 2
       content
       morecontent
    
  • If the contents of an item in a list span more than one line, the lines following the first line should have their indentation starting at the same level as the content on the first line. I.e.:

    - This is the first line
      this is the second line
      this is the third line
      notice the indentation