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: