Documentation¶

Generation¶

The documentation of CSO that you are reading right now is generated from CSO source files. To (re)generate it, run in the main directory:

make docu

The documentation files are formatted for use with ‘Sphinx’; see:

Sphinx homepage

The formatting of documentation is done using ‘reStructuredText’, see for example:

The ‘Sphink’ python package should be available to be able to (re)generate the documentation. If not available on your system yet, see below for installation instructions.

Source files¶

The main files of the documentation are located in:

./doc/source/

Parts of the documentation are included in the various Python modules and scripts. The documentation is configured in such a way that these are automatically incorporated.

The source tree of the documentation files is:

index.rst

tutorial.rst

pymod-cso.rst

pymod-cso_catalogue.rst

pymod-cso_constants.rst

pymod-cso_file.rst

pymod-cso_gridded.rst

pymod-cso_plot.rst

pymod-cso_s5p.rst

pymod-cso_scihub.rst

pymods.rst

documentation.rst

Installation of Sphinx¶

To check if Sphinx is already installed, try to run the quick-start script:

sphinx-quickstart --version

sphinx-quickstart 2.4.0

If not available yet, try to install using one of the following methods.

Install Sphinx¶

Try if it is possible to download and install Sphinx using one of the standard installation commands.

For an Anaconda distribution, try:
```
conda install -c anaconda sphinx
```
For other distributions, try:
```
pip install sphinx
```

Build Spinx from source¶

Download the latest version from the Sphinx homepage, for example:

Sphinx-3.0.3.tar.gz

To let the package be installed at a local destination, define the following environment variable:

export PYTHON_PREFIX="${HOME}/opt/Python-3.7"

Build and install in the user-defined location using:

cd Sphinx-3.0.3
python setup.py install --user

Extend the search path with:

export PATH="${PYTHON_PREFIX}/bin:${PATH}"

Configuration¶

The source of the documentation is located in (subdirectories of):

./doc/

In this directory, the Sphinx quick start command has been called:

sphinx-quickstart \
  --sep \
  --project='CSO' \
  --author='Arjo Segers' \
  --ext-autodoc \
  --ext-intersphinx \
  --ext-mathjax \
  --no-batchfile

The following entities have been created now:

source directory to hold the documenation source files; initially the following files are created:
- conf.py : configuration file;
- index.rst : source of the main page of the documentation;
build directory to hold the generated documenation;
Makefile : make commands.

In the ./doc/source/conf.py file created in this way, the following changes were made manually:

the location of the python modules was added to the search path;
added options for autodoc entries;
added options for intersphinx entries;
the html theme was changed.

The initial documentation could be created using:

(cd doc; make html)

How to add a new module to the documentation?¶

Example taken from introduction of the ‘cso_s5p’ module.

Create new module file:
```
touch  py/cso_s5p.py
```
Create a documentation file specific for the new module:
```
doc/source/pymod-cso_s5p.rst
```
which only refers to the documentation included in the module:
```
.. automodule:: cso_s5p
```

Add a reference to the new module in the Python modules page in the file pymods.rst:

.. toctree::
   :maxdepth: 1

   pymod-cso_scihub
   pymod-cso_s5p              <---
   :

Add a reference to the module documentation to the top-level table-of-content in index.rst:

.. toctree::
   :maxdepth: 2

   tutorial
   cso_s5p                    <---
   pymods
   documentation