automated api level html documentation

[martin-rdz]

Rationale

Currently, the documentation in not very accessible and spread across various locations, such as the readme.md, doc folder, inline comments. Especially new contributors (and non-matlab-experts) are easily overwhelmed ;)

Proposed solution

Use the documentation generator sphinx, which is well established for python documentation. A prime example of an sphinx documentation is xarray.

The sphinxcontrib-matlabdomain extension extends the functionality to matlab. With the recommonmark extension, the markdown formatted readme and some of the files from the doc folder can be automatically included.

A basic setup of sphinx is done in the branch setup_autodoc. I decided not to file a pull request yet, as we might require some modifications to the inline docstrings (see below). An example of the html rendered version can be found here. This page can also be moved to a PollyNET githubpage later.

Challenges

• The inline docstrings have to conform certain formatting, see sphinx.ext.napoleon and the matlabdomain example
• To be displayed correctly in the html version, the markdown tables, especially in the doc folder have should obey the commonmark specification

How to run sphinx

• install the python libraries sphinx recommonmark sphinx_rtd_theme sphinxcontrib-matlabdomain

• [switch to the setup-autodoc branch]

• cd doc-auto/

• make html, the build target is defined in the Makefile

• Further documentation and modifications to the structure can be done in the reStructuredText files in doc-auto/source

[ZPYin]

Thanks for your cool suggestion.

I've discussed with @HolgerPollyNet regarding hosting the documentation on GitHub wiki. Because it's easier for others to collaborate with.

But compared with sphinx docs, it also has many disadvantages (I just googled around):

• No rendering for formulas, which is essential for explaining algorithms.
• Tied with GitHub repo.

So, Sphinx might be more suitable for our purpose. I will explore Sphinx in the next few days, maybe start with the repo you setup for Pollynet_processing_chain.

[ZPYin]

A drafted version of Picasso documentation (based on Sphinx) has been uploaded, see the link below: https://pollynet.github.io/Pollynet_Processing_Chain/

Right now there are still limited information, but can be easily extended. The source files are located under doc-auto/ and the build folder is docs (restricted by GitHub Pages).