Skip to main content

ZC.buildout recipe to generate and build Sphinx-based documentation in the buildout.

Project description

Detailed Documentation

What is Sphinx ?

Sphinx is the rising tool in the Python community to build documentation. See http://sphinx.pocoo.org.

It is now used for instance by Python. See http://docs.python.org/dev.

Sphinx uses reStructuredText, and can be used to write your buildout-based application. This recipe sets everything up for you, so you can provide a nice-looking documentation within your buildout, in static html or even PDF.

The fact that your documentation is managed like your code makes it easy to maintain and change it.

Quick start

To use the recipe, add in your buildout configuration file a section like this:

[buildout]
parts =
    ...
    sphinx
    ...

[sphinx]
recipe = collective.recipe.sphinxbuilder

That’s it ! Run your buildout and you will get:

  • a new script in the bin folder, called sphinx

  • a docs directory containing your documentation.

To build your documentation, just run the sphinx script:

$ bin/sphinx

You will get a shiny Sphinx documenation in docs/build/html. To write your documentation, go in docs/source. Everytime source is modified, run the script again.

A good starting point to write your documentation is: http://sphinx.pocoo.org/contents.html.

Supported options

The recipe supports the following options:

doc-directory

Specify the documentation root. Default to docs.

doc-outputs

Multiple-line value that defines what kind of output to produce. Can be html, latex or pdf. Defaults to html.

script-name

The name of the script generated. Defaults to the name of the section.

sphinx-project

The name of the project used in Plone. Defaults to Plone.

sphinx-extensions

Sphinx extensions in use. Defaults to none.

sphinx-master

Name of the index file. Defaults to index.

sphinx-year

Year of the project. Defaults to current year.

sphinx-suffix

File extensions used for reST file. Defaults to .txt

sphinx-author

Author. Defaults to Plone Community.

sphinx-version

Version. Defaults to 1.0.

sphinx-release

Release. Defaults to 1.0.

sphinx-dot

The prefix of the static and template directory. Defaults to ‘.’ under Linux and ‘_’ under Windows.

sphinx-sep

Separate source and build directories. (Y or N) Defaults to Yes.

sphinx-logo

Logo used for html and pdf. Defaults to plone.png (which is provided by the recipe)

sphinx-css

css file used to change Sphinx look. Defaults to plone.css (which is provided by the recipe)

sphinx-latex-options

extra latex options file used in Sphinx. Defaults to options.tex provided by the recipe.

Example usage

The recipe can be used without any options. We’ll start by creating a buildout that uses the recipe:

>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinx
...
... [sphinx]
... recipe = collective.recipe.sphinxbuilder
... """)

Let’s run the buildout:

>>> print 'start', system(buildout)
start...
Installing sphinx.
Generated script '/sample-buildout/bin/sphinx-build'.
<BLANKLINE>

What are we expecting ?

A docs folder with a Sphinx structure:

>>> docs = join(sample_buildout, 'docs')
>>> ls(docs)
- Makefile
d source

>>> source = join(docs, 'source')
>>> ls(source)
d  .static
d  .templates
-  conf.py
-  index.txt

>>> ls(join(source, '.templates'))
-  layout.html
-  modindex.html
-  search.html

>>> ls(join(source, '.static'))
-  options.tex
-  plone.css
-  plone_logo.png

A script in the bin folder to build the docs:

>>> bin = join(sample_buildout, 'bin')
>>> ls(bin)
- buildout
- sphinx
- sphinx-build

The content of the script is a simple shell script:

>>> script = join(sample_buildout, 'bin', 'sphinx')
>>> print open(script).read()
cd ...docs
make html

If we want latex and pdf, we need to explicitly define it:

>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinx
...
... [sphinx]
... recipe = collective.recipe.sphinxbuilder
... doc-outputs =
...     html
...     latex
...     pdf
... """)
>>> print 'start', system(buildout)
start...
Installing sphinx.
<BLANKLINE>

Let’s see our script now:

>>> print open(script).read()
cd ...docs
make html
make latex
make latex && cd ... && make

Finally let’s run it:

>>> print 'start', system(script)
start mkdir -p build/html build/doctrees
...
Transcript written in modPlone.ilg.
<BLANKLINE>

We should have some nice reST file:

>>> print open(join(docs, 'source', 'index.txt')).read()
.. Plone documentation master file, ...
<BLANKLINE>
Welcome to Plone's documentation!
=================================
<BLANKLINE>
Contents:
<BLANKLINE>
.. toctree::
   :maxdepth: 2
<BLANKLINE>
Indices and tables
==================
<BLANKLINE>
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
<BLANKLINE>
<BLANKLINE>

And the html rendering should use the plone logo:

>>> html = open(join(docs, 'build', 'html', 'index.html')).read()
>>> 'plone_logo.png' in html
True

Contributors

Tarek Ziadé, Author

Change history

0.1.1 (2008-09-11)

  • Using a sphinx-build local to the environment [Tarek]

0.1.0 (2008-09-10)

  • Initial implementation [Tarek Ziadé]

  • Created recipe with ZopeSkel [Tarek Ziadé].

Download

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

collective.recipe.sphinxbuilder-0.1.1.tar.gz (21.0 kB view details)

Uploaded Source

File details

Details for the file collective.recipe.sphinxbuilder-0.1.1.tar.gz.

File metadata

File hashes

Hashes for collective.recipe.sphinxbuilder-0.1.1.tar.gz
Algorithm Hash digest
SHA256 04142865cf64e907bc70a1f41f29a6025b1ef2a53b01d61d6580755069387fdd
MD5 e286f2d3af5f8433d5fecd5dbf1cb5b8
BLAKE2b-256 8e97242c55497af20115d665205d04dc2aea842cbc1c577007a1910196e10bf5

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page