Saqc documentation "pipeline"

Saqc documentation toolchain (is that the right word actually?)

This is a semi generic documentation pipeline - it is implemented with respect to its use in the current saqc repository - due to timelimitation this is not a stand alone or independent docu pipeline. You may find some things hard coded, not all the parameters and work steps are accessable via sophisticated interfaces.

All documentation related stuff (exept from the repos readme.md introduction) is now living in the sphinx-doc folder. (Including the getting_started markdown files that where in the "saqc/docs".)

Run make -doc from the "sphinx-doc" directory to generate the pages and get an impression.

The MR is not concerned with the specific design of the pages or documentation content generation - its just about the infrastructure and workflow of docu generation.

Having a look into the "Makefile", you can see there are called 4 scripts to generate the documentation:

• make_doc_module.py

  • Generates temporal modules from the actual saqc modules.
  • Certain parameter sections get removed from the parameter docstrings (data, flagger).
  • Returns section is removed
  • depending on the mode passed, a mirror of the module to be documented is generated, or the module elements are regrouped into custom modules (BasicFlagging, AdvancedFlagging, ...)

• make_doc_rst.py

  • generate the automodapi rest files for the modules to be documented.
  • some parameter sets for the automodapi directive are hardcodedly included
  • include all imports in the directives skip list

• make_md_to_rst.py

  • Generate rest files form markdown files
  • redirect hyperlinks/crosslinks
  • repair/redirect section links
  • repair tables/picture inclusion

• run sphinx (with passed configurations)

• make_html_headings_proppa.py

  • override the module domain strings in the resulting html build, so that they represent the intended module structure (basically: remove docs.*. part.

I integrated a "documentation guide" page in the dokumentation. See here directly.