Documenting code with Sphinx¶
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
can be used to build various flavors of documentation. Assuming that the
Sphinx scripts are installed in
$ 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
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