Introduction to Sphinx and ReadTheDocs Greg Back November 19, 2014 /gtback #pynash

Overview ● Docstrings ● Sphinx (+ docutils) ● ReadTheDocs

Docstrings ● “Magic” strings to comment modules, classes, and functions. ● Access with X.__doc__ or help(X) ● Distinct from comments ○ Describe WHAT the code does, not HOW.

PEP 257: Docstring Conventions ● Use """triple double quotes""". ● First line is a summary. ○ Use initial capital and period. ○ Phrase as a command, not a description. ● Include blank line before longer description.

# indoctrin8/subjects.py """ Docstring for the ``subjects`` module. """ class Person(object): """A person to be indoctrinated.""" def __init__(self, name): """Build a new Person. Args: name (str): What the person likes to be called. """ self.name = name def say_hello(self): """Greet the Person, warmly.""" print "Hello, %s" % self.name

PEP 257: Docstring Conventions What to document? ● Entire public interface. ● For functions, arguments and return values. ○ PEP257 does not specify a format, but docutils does.

PEP 257: Docstring Conventions For historical reference (Rejected): ● PEP 256: Docstring Processing System Framework ● PEP 258: Docutils Design Specification

Sphinx ● De-facto standard for Python documentation ● Used for docs.python.org ● Depends on docutils ● $ pip install sphinx ● $ sphinx-quickstart ● $ sphinx-apidoc ● $ make html

reStructuredText ● Formatting language similar to Markdown ● Used by docutils/Sphinx ● Designed to support multiple output formats ● More “capable” than Markdown ● More “complex” than Markdown ● Better for multi-page web sites WARNING: OPINIONS

sphinx-quickstart ● Prompts for some frequently-used settings ● Asks which extensions to enable ● Creates conf.py, Makefile, index.rst

Welcome to indoctrinate's documentation! ======================================== Installation ------------ Use pip_: .. code-block:: bash $ pip install indoctrinate You might also want to consider using a virtualenv_. .. note:: I wouldn't recommend actually installing this, since it doesn't really do anything! .. _pip: http://pip.readthedocs.org/ .. _virtualenv: http://virtualenv.readthedocs.org/

sphinx-apidoc $ sphinx-apidoc -o docs/api indoctrin8 Creating file docs/api/indoctrin8.rst. Creating file docs/api/modules.rst. Don’t forget to add api/modules.rst to the table of contents!

indoctrin8 package ================== Submodules ---------- indoctrin8.subjects module -------------------------- .. automodule:: indoctrin8.subjects :members: :undoc-members: :show-inheritance: Module contents --------------- .. automodule:: indoctrin8 :members: :undoc-members: :show-inheritance:

Built-in Sphinx Themes

Other Sphinx Themes

Sphinx Extensions ● autodoc (API documentation) ● viewcode (include syntax-highlighted code) ● intersphinx (crosslinking) ● doctest (include tests in documentation) ● mathjax (rendering mathematical equations) ● … others

API Documentation

Viewcode extension

Cleaner Docstrings with Napoleon Standard Docstrings can be difficult to read: :param path: The path of the file to wrap :type path: str :param field_storage: The :class:`FileStorage` instance to wrap :type field_storage: FileStorage :param temporary: Whether or not to delete the file when the File instance is destructed :type temporary: bool :returns: A buffered writable file descriptor :rtype: BufferedFileStorage

Napoleon Marching towards legible docstrings Args: path (str): The path of the file to wrap field_storage (FileStorage): The :class:`FileStorage` instance to wrap temporary (bool): Whether or not to delete the file when the File instance is destructed Returns: BufferedFileStorage: A buffered writable file descriptor Sphinx < 1.3 pip install sphinxcontrib-napoleon extensions += ['sphinxcontrib.napoleon'] Sphinx >= 1.3 extensions += ['sphinx.ext.napoleon']

Alternative to Sphinx MkDocs: ● Markdown-based (rather than reST) ● Used by Django REST Framework A brief diversion

Read the Docs ● Hosts sphinx-built documentation for Python projects (and others) ● Alternative to pythonhosted.org Features ● Multiple versions ● Multiple languages ● Multiple output formats ● Automatic builds (GitHub webhook)

Read the Docs 1. Go to https://readthedocs.org 2. Sign up for an account. 3. Click on “Import a project”. 4. Add project URL and other information. 5. Wait for first build to complete. 6. Add Service Hook on GitHub.

Adding a GitHub hook

Documentation on Read the Docs

Read the Docs menu

Links Example Project https://github.com/gtback/indoctrinate https://pypi.python.org/pypi/indoctrinate http://indoctrinate.readthedocs.org/en/latest/ PEP 257 https://www.python.org/dev/peps/pep-0257/ Sphinx http://sphinx-doc.org/ Napoleon http://sphinxcontrib-napoleon.readthedocs.org/ Read the Docs https://readthedocs.org/ Sphinx Themes http://sphinx-doc.org/theming.html https://github.com/snide/sphinx_rtd_theme https://github.com/bitprophet/alabaster

Other Documentation Resources ● http://docs.python-guide.org/en/latest/writing/documentation/ ● http://docs.writethedocs.org/ ● http://jacobian.org/writing/great-documentation/ ● Projects with great documentation: ○ Django ○ Flask ○ Requests ○ Celery ○ pymongo