Use Sphinx to build documentation for zope.org.
Project description
Introduction
This buildout recipe aids in the generation of documentation for the zope.org website from restructured text files located in a package. It uses Sphinx to build static html files which can stand alone as a very nice looking website.
Usage Instructions
Suppose you have a package called z3c.form. In the setup.py for z3c.form it is recommended that you add a docs section to the extras_require argument. It should look something like this:
extras_require = dict( docs = ['Sphinx', 'z3c.recipe.sphinxdoc'] )
Then in the buildout.cfg file for your package, add a docs section that looks like this:
[docs] recipe = z3c.recipe.sphinxdoc eggs = z3c.form [docs]
Be sure to include it in the parts, as in:
[buildout] develop = . parts = docs
Now you can rerun buildout. The recipe will have created an executable script in the bin directory called docs.
This script will run the Sphinx documentation generation tool on your source code. By default, it expects there to be an index.txt file in the source code. In this case, index.txt would have to be in src/z3c/form/index.txt. This file can be a standard restructured text file, and can use all the sphinx goodies. For example, your index.txt might look like this:
Welcome to z3c.form's documentation! ==================================== Contents: .. toctree:: :maxdepth: 2 README Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
You should read the documentation for Sphinx to learn more about it. It is available here: http://sphinx.pocoo.org/
Now you should be able to run the docs script:
$ ./bin/docs
This generates all the documentation for you and placed it in the parts directory. You can then open it up in firefox and take a look:
$ firefox parts/docs/z3c.form/build/index.html
And that’s it!
CHANGES
0.0.5 (2008-05-11)
Initial release.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for z3c.recipe.sphinxdoc-0.0.5.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | bf9f93b7afc5c7825f17d6d5282c9f8f7289991742822ce21c3ae7c61a46db64 |
|
MD5 | a0ae456440cab972c280df9446403624 |
|
BLAKE2b-256 | d95d5e0a04795fcfdc3bf383c05f64a9b58c3cb7c80bc2faf29cc2195866f812 |