Introduction#

This is a demo show-casing how to document a Python library with Sphinx, including the library’s public API via the Autodoc and Autosummary extensions. It uses reStructuredText (reST) in its hand-written documents as well as in the doc-strings embedded with the library code.

The demo here is the yard stick to compare a Markdown-based workflow against:

  • demo-MyST-docstring: Also uses the Sphinx documentation system, but has MyST parse the source files and doc-strings as Markdown instead of reST.

  • demo-MkDocstrings: Uses MkDocs with the MkDocstrings plug-in. This is an entirely different documentation build system that uses Markdown throughout.

As for this demo, you can click on “Show Source” at the bottom of every page to see the reStructuredText from which it was rendered.

GitHub repo