
Python Documentation Using Sphinx - keyboardman
https://leimao.github.io/blog/Python-Documentation-Using-Sphinx/
======
westurner
I usually generate new Python projects with a cookiecutter; such as
cookiecutter-pypackage. I like the way that cookiecutter-pypackage includes a
Makefile which has a `docs` task so that I can call `make docs` to build the
sphinx docs in the docs/ directory which include:

\- a /docs/readme.rst that includes the /README.rst as the first document in
the toctree

\- a sensible set of default documents: readme (.. include:: /README.rst),
installation, usage, modules (sphinx-autodoc output), contributing, authors,
history (.. include:: /HISTORY.rst)

\- a sphinx conf.py that sets the docs' version and release attributes to
pkgname.__version__; so that the version number only needs to be changed in
one place (as long as setup.py or setup.cfg also read the version string from
pkgname.__version__)

\- a default set of extensions: ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
that generates API docs and includes '[source]' hyperlinks from the generated
API docs to the transcluded syntax-highlighted source code and links back to
the API docs from the source code

[https://github.com/audreyfeldroy/cookiecutter-
pypackage/tree...](https://github.com/audreyfeldroy/cookiecutter-
pypackage/tree/master/%7B%7Bcookiecutter.project_slug%7D%7D/docs)

------
westurner
There are a few styles of docstrings that Sphinx can parse and include in docs
with e.g. sphinx-autodoc:

`:param, :type, :returns, :rtype` docstrings (which OP uses; and which
pycontracts can read runtime parameter and return type contracts from
[https://andreacensi.github.io/contracts/](https://andreacensi.github.io/contracts/)
(though Python 3 annotations are now the preferred style for compile or
editing-time typechecks))

Numpydoc docstrings:
[https://numpydoc.readthedocs.io/en/latest/format.html](https://numpydoc.readthedocs.io/en/latest/format.html)

Googledoc docstrings: [https://sphinxcontrib-
napoleon.readthedocs.io/en/latest/](https://sphinxcontrib-
napoleon.readthedocs.io/en/latest/)

------
westurner
You can use Markdown with Sphinx in at least three ways:

MyST Markdown supports Sphinx and Docutils roles and directives. Jupyter Book
builds upon MyST Markdown. With Jupyter Book, you can include Jupyter
notebooks (which can include MyST Markdown) in your Sphinx docs. Executable
notebooks are a much easier way to include up-to-date code outputs in docs.
[https://myst-parser.readthedocs.io/en/latest/](https://myst-
parser.readthedocs.io/en/latest/)

Sphinx (& ReadTheDocs) w/ recommonmark:
[https://docs.readthedocs.io/en/stable/intro/getting-
started-...](https://docs.readthedocs.io/en/stable/intro/getting-started-with-
sphinx.html#using-markdown-with-sphinx)

Nbsphinx predates Jupyter Book and doesn't yet support MyST Markdown, but does
support Markdown cells in Jupyter notebooks. Nbsphinx includes a parser for
including .ipynb Jupyter notebooks in Sphinx docs. nbsphinx supports raw RST
(ReST) cells in Jupyter notebooks and has great docs:
[https://nbsphinx.readthedocs.io/en/latest/](https://nbsphinx.readthedocs.io/en/latest/)

Nbdev is another approach; though it's not Sphinx:

> _nbdev is a library that allows you to fully develop a library in Jupyter
> Notebooks, putting all your code, tests and documentation in one place._

> [...] _Add %nbdev_export flags to the cells that define the functions you
> want to include in your python modules_

[https://github.com/fastai/nbdev](https://github.com/fastai/nbdev)

A few additional sources of docs for Sphinx and ReStructuredText:

Read The Docs docs > Getting Started with Sphinx > External Resources
[https://docs.readthedocs.io/en/stable/intro/getting-
started-...](https://docs.readthedocs.io/en/stable/intro/getting-started-with-
sphinx.html#external-resources)

CPython Devguide > "Documenting Python"
[https://devguide.python.org/documenting/](https://devguide.python.org/documenting/)

"How to write [Linux] kernel documentation"
[https://www.kernel.org/doc/html/latest/doc-
guide/index.html](https://www.kernel.org/doc/html/latest/doc-guide/index.html)

awesome-sphinxdoc: [https://github.com/yoloseem/awesome-
sphinxdoc](https://github.com/yoloseem/awesome-sphinxdoc)

... "Ask HN: Recommendations for Books on Writing [for engineers]?"
[https://news.ycombinator.com/item?id=23945580](https://news.ycombinator.com/item?id=23945580)

