Introduction to Sphinx and ReadTheDocs

Writing documentation isn't always as fun as coding, but it's a crucial aspect of attracting users and other developers to your project. In this talk, I cover how to get started with about Sphinx, the de facto standard Python documentation generator, and ReadTheDocs, the easiest way to host the resulting documentation. And they're not just for Python, either!

Transcript

1. Introduction to Sphinx and ReadTheDocs Greg Back November 19, 2014 /gtback #pynash
2. Overview • Docstrings • Sphinx (+ docutils) • ReadTheDocs
3. 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.
4. 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.
5. # 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
6. 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.
7. PEP 257: Docstring Conventions For historical reference (Rejected): • PEP 256: Docstring Processing System Framework • PEP 258: Docutils Design Specification
8. Sphinx • De-facto standard for Python documentation • Used for docs.python.org • Depends on docutils • $ pip install sphinx • $ sphinx-quickstart • $ sphinx-apidoc • $ make html
9. 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
10. sphinx-quickstart • Prompts for some frequently-used settings • Asks which extensions to enable • Creates conf.py, Makefile, index.rst
11. 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/
12. 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!
13. indoctrin8 package ================== Submodules ---------- indoctrin8.subjects module -------------------------- .. automodule:: indoctrin8.subjects :members: :undoc-members: :show-inheritance: Module contents --------------- .. automodule:: indoctrin8 :members: :undoc-members: :show-inheritance:
14. Built-in Sphinx Themes
15. Other Sphinx Themes
16. Sphinx Extensions • autodoc (API documentation) • viewcode (include syntax-highlighted code) • intersphinx (crosslinking) • doctest (include tests in documentation) • mathjax (rendering mathematical equations) • … others
17. API Documentation
18. Viewcode extension
19. 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
20. 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']
21. Alternative to Sphinx MkDocs: • Markdown-based (rather than reST) • Used by Django REST Framework A brief diversion
22. 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)
23. 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.
24. Adding a GitHub hook
25. Documentation on Read the Docs
26. Read the Docs menu
27. 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
28. 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