Documentation generation

Goal

• The documentation should be very close to the MicroPython documentation.

Decisions

• Sphinx

• autodoc

• Support for: reStructuredText

• Support for: Markdown

• VSCode Extensions

• Manually push documentation to octoprobe.org

• Forward from octoprobe.readthedocs.io to octoprobe.org

Based on Flask documentation

Flask makes intense use of autodoc. Therefore I used Flask as a base.

• Documentatation: https://flask.palletsprojects.com/en/3.0.x/api/#application-object

• Requirements: https://github.com/pallets/flask/blob/main/requirements/docs.in

• Config: https://github.com/pallets/flask/blob/main/docs/conf.py

• Index: https://github.com/pallets/flask/blob/main/docs/index.rst

Evaluation of the theme

• See: docs/conf.py html_theme = “sphinx_rtd_theme”

• See: https://www.sphinx-doc.org/en/master/examples.html

Page width: The page width for all themes seems to be the same: The width is 100% of the window to some limit. Then there is a hard limit.

• Theme classic * …

• Theme alabaster

  • pip install -

    Positive: no dependency

  • html_sidebars support unknown.

• Theme sphinx_rtd_theme

  • pip install sphinx_rtd_theme

    Positive: maintained by sphinx

  • Used by: https://docs.micropython.org

    Positive: known by the micropython community

  • html_sidebars is NOT supported!

    Negative

• Theme sphinx13 * Used by: https://www.sphinx-doc.org/en/master/ https://github.com/sphinx-doc/sphinx/blob/master/doc/conf.py

  Positive: Sphinx documentation ‘another builtin theme’ * inherit = “basic”, https://github.com/sphinx-doc/sphinx/blob/master/doc/_themes/sphinx13/theme.toml#L2C1-L2C18

  Need investigation: Where does it come from? * html_sidebars support unknown. * Positive: Deep hierarchy helps to structure the documentation

• Theme flask

  • pip install pallets-sphinx-themes

    Negative: externally maintained

  • Used by: https://flask.palletsprojects.com

    Negative: May change, not widely used

  • html_sidebars support unknown.

• Theme python_docs_theme

  • pip install python-docs-theme

    Negative: externally maintained

  • Used by: https://docs.python.org

    Positive: Probably mature and stable

  • html_sidebars IS supported!

    Positive