Documenting code with Sphinx

Note

This outline needs fleshing out.

One of the most valuable contributions that non-core developers make is helping keep a project’s documentation up-to-date and useful.

Each Zope packages should have its own documentation, managed within the project itself. This documentation is maintained as a set of files in the docs subdirectory of the project, containing source files in “restructured text” format (see the reStructuredText Refererence) as well as control files which convert those source texts into HTML, Latex, PDF, etc., using Sphinx (see the Sphinx manual).

The top-level document is conventionally docs/index.rst. This document should explain the purpose of the project, and will often link to other documents outlining usage, APIs, etc.

Building the HTML Documentation

If you have Sphinx installed somewhere on your system, the docs/Makefile can be used to build various flavors of documentation. Assuming that the Sphinx scripts are installed in /opt/Sphinx/bin:

$ cd /tmp
$ git clone https://github.com/zopefoundation/Zope.git
$ cd Zope/docs
$ PATH=/opt/Sphinx/bin:$PATH make html

After running that command, you can view the generated docs in your browser, just open /tmp/Zope/docs/_build/html/index.html

Re-running the make html command after making changes to the docs lets you see the rendered HTML corresponding to your updates.

You can also use the Sphinx doctest extension to test example code snippets in the documentation:

$ PATH=/opt/Sphinx/bin:$PATH make doctest