Documentation

The most popular tool for writing Python documentation is Sphinx, and the most popular host for it is Read the Docs (RTD). Sphinx uses reStructuredText_ for its markup language. The generator gives a skeleton for your documentation in the docs directory 🔗.

Defaults

  • There are many themes for Sphinx, but the generator chooses the RTD theme. It is designed to look good on desktop and mobile devices.
  • The latest stable version of Sphinx is 2.0, but it is not yet compatible with the RTD theme. For now, the generator chooses the latest 1.x version.
  • The documentation is versioned with your code. The generated configuration reads the version from pyproject.toml, the single source of truth for package metadata.
  • The generator includes a style sheet that will wrap table text for you. (Thanks to Rackspace!)
  • The landing page is generated from index.rst. By default, it includes a section of content from the project README (so that you don’t have to write it twice). Initially, that content is the project name and the project badges.

Editing

You can edit the landing page by editing index.rst. If you want to add more pages (“chapters”), then add new reStructuredText files to the docs directory and link them from the toctree in index.rst.

While you’re working on documentation, you can use the serve script to launch a server for the HTML build of your documentation. Whenever you change a file, the server will rebuild your documentation and refresh your browser:

$ poetry run invoke serve

Publishing

When you’re ready to publish your documentation on Read the Docs, follow these steps:

  • Log in to Read the Docs with your GitHub credentials.
  • Import your project repository. (You may likely need to refresh the list.)
  • Click “Build version” for the first build. Subsequent builds are automatically triggered when you push to GitHub.