3 ms·

Python Documentation Using Sphinx

1 points by keyboardman 6y ago

westurner 6y ago
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-with-sphinx.html#using-markdown-with-sphinx https://docs.readthedocs.io/en/stable/intro/getting-started-... 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-with-sphinx.html#external-resources https://docs.readthedocs.io/en/stable/intro/getting-started-... 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
westurner 6y ago
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 6y ago
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/master/%7B%7Bcookiecutter.project_slug%7D%7D/docs https://github.com/audreyfeldroy/cookiecutter-pypackage/tree...

1 points by keyboardman 6y ago

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-with-sphinx.html#using-markdown-with-sphinx https://docs.readthedocs.io/en/stable/intro/getting-started-... 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-with-sphinx.html#external-resources https://docs.readthedocs.io/en/stable/intro/getting-started-... 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

westurner 6y ago

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 6y ago

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/master/%7B%7Bcookiecutter.project_slug%7D%7D/docs https://github.com/audreyfeldroy/cookiecutter-pypackage/tree...