Repository Setup

This documents the process done to setup the repository to automatically generate documentation with readthedocs, run unit tests at the right time, and integrate with CodeCov.

Documentation

Documentation is automatically generated using Readthedocs for data in the docs directory.

Readthedocs uses Sphinx to generate documentation which requires reStructuredText (.rst) files containing documentation and layout information. Additionally it requires a configuration file conf.py to store template information and state what plugins to use. The basic setup was created using these commands:

sphinx-quickstart
sphinx-apidoc -o . ../openep

The generated conf.py file was modified to add the current and parent directories to sys.path, add 'sphinx.ext.autodoc' to the list of used extensions, and changing the html theme. This will generate .rst files for existing modules and it's into these that contributors should write explanatory information and manage other content. As new modules are added these may require new .rst files to be added. Docstrings in the actual code will also be imported and used to generate documentation automatically. For more info on Sphinx here is the quickstart.

Readthedocs additionally depends on the .readthedocs.yaml file in the project root. The default one is used here which states what config file to use, what Python version, and where requirements are found.

Readthedocs needs to be linked to a repository, this is done by logging into the website with Github credentials and selecting to setup the appropriate repository. Once the instructions have been followed it should show up as a webhook in the repository's settings.

Unit tests

Basic unit tests are implemented here as a Github action, which runs at particular trigger times in Github hosted VMs. These are setup through YAML files in the .github/workflows directory. A new workflow can be created by clicking on the Actions tab of the repository and selecting "New workflow". The one used here is based off the basic