References

Sphinx and Rest References

• This doc began as a fork of a 2011 version of Cristoph Reller reST Memo which is now part of his Programming Notes. I adapted it according to my needs, and they have largely diverged now, but it may still inherits from few content and layout.

• Sphinx documentation
• Sphinx reStructuredText Primer
• Documenting Your Project Using Sphinx from an example pypi project’s
• Awesome Sphinx a curated list of awesome extra libraries, software and resources for Sphinx.
• Thomas Cokelaer Openalea project: How to use sphinx ? and Sphinx and RST syntax guide.
• The ReStructuredText Documentation
  • Docutil reStructuredText Primer you may prefer the python the Sphinx nicely formated documentation cited above, also available with a distinct layout as docs.python: reStructuredText Primer
  • Quick reStructuredText
  • reStructuredText Markup Specification
  • reST Directives
  • Interpreted Text Roles
  • ReStructuredText Demonstration
• Emacs Support for reStructuredText
• Documenting Python in the Python Developer’s Guide
• sampledoc tutorial from matplotlib a python 2D plotting library.
• rst2pdf is a tool for transforming reStructuredText to PDF using ReportLab. It supports Sphinx formatting.
• Epydoc reST markup

How to write docstrings

• Look at examples in Official list of projects using Sphinx
• Documenting Python use Sphinx in function definitions it prefers to the pure Sphinx Syntax the Google style guide that is used in Full Code Example
• OpenAlea has a nice comparaison of three ways of filling the docstring. which compare Pure sphinx code, restructuredText and Sphinx, Numpy style. But it predates the Napoleon extension, so the cause of rejecting Numpy may be no longer valid. The source is template.py
• Google style guide.
• NumPy style guide.
• Sources of mongo python driver are also a good example

Extending Sphinx

• Sphinx Tutorial: Writing a simple extension.
• Creating Custom Link Roles.
• Defining Custom Roles in Sphinx a Sphinx blog post by Doug Hellmann
• Creating Interpreted Text Roles from docutils project.
• Creating reStructuredText Directives from docutils project.