Documentation

#Tools #Python #Documentation

I would vote for two very different documentation tools for a data science project,

Sphinx docs

Sphinx docs is a mature and stable. I love reStructuredText as the syntax as it is very versatile. It supports math, figures with captions, admonitions, cross reference, auto doc from docstrings, cross project cross referencing, pdf generation, etc.

squidfunk/mkdocs-material

squidfunk’s mkdocs-material is a rather light-weight but is also growing to be versatile now. The engine is mkdocs. mkdocs-material is a theme but provides a lot of useful and easy to use elements.

The package ships a lot of plugins and extensions for documentation. We can generate docs from docstrings, write admonitions, write math, etc. We can also install plugins to extend the functions, e.g., pdf generation.

One more thing, mkdocs-material is prettier than most sphinx docs themes.

Which on to use

If you have never used sphinx, I recommend starting from mkdocs-material. But it is really just a personal taste.

Roll a dice.

Published: by ;

L Ma (2021). 'Documentation', Datumorphism, 08 April. Available at: https://datumorphism.leima.is/wiki/tools/documentation/.

Current Ref:

  • wiki/tools/documentation.md