ZC.buildout recipe to generate and build Sphinx-based documentation in the buildout.
Project description
.. contents::
- Code repository: https://github.com/sdouche/collective.recipe.sphinxbuilder
- Documentation: http:/docs.garbas.si/collective.recipe.sphinxbuilder
- Questions and comments to tarek_at_ziade.org, rok_at_garbas.si, sdouche_at_sdouche.com
Detailed Documentation
**********************
===============
What is Sphinx?
===============
Sphinx is the mainly 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 and many
others
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, PDF or even
epub.
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 =
...
sphinxbuilder
...
[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
source = ${buildout:directory}/docs-source
build = ${buildout:directory}/docs
Run your buildout and you will get a few new scripts in the `bin` folder,
called:
- `sphinx-quickstart`, to quickstart sphinx documentation
- `sphinxbuilder`, script that will
To quickstart a documentation project run, as you would normaly do with Sphinx::
$ bin/sphinx-quickstart
and anwser few questions and choose `docs-source` as you source folder.
To build your documentation, just run the sphinx script::
$ bin/sphinxbuilder
That's it!
You will get a shiny Sphinx documenation in `docs/html`.
Write your documentation, go in `docs-source`.
Everytime source is modified, `sphinxbuilder` run script again.
A good starting point to write your documentation is:
http://sphinx.pocoo.org/contents.html.
=======
Plone 4
=======
Usage with Plone 4 is even easier::
[buildout]
parts =
...
sphinxbuilder
...
[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
interpreter = ${buildout:directory}/bin/zopepy
Follow quick-start tutorial and do not forget to add interpreter with
installed eggs to access your sourcecode with Sphinx.
=================
Supported options
=================
The recipe supports the following options:
build (default: `docs`)
Specify the build documentation root.
source (default: `{build-directory}/source`)
Speficy the source directory of documentation.
outputs (default: `html`)
Multiple-line value that defines what kind of output to produce.
Can be `doctest`, `html`, `latex`, `pdf` or `epub`.
script-name (default: name of buildout section)
The name of the script generated
interpreter
Path to python interpreter to use when invoking sphinx-builder.
extra-paths
Extra paths to be inserted into sys.path.
products
Extra product directories to be extend the Products namespace for
old-style Zope Products.
=============
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 = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... """)
Let's run the buildout::
>>> print 'start', system(buildout)
start Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
Generated script '/sample-buildout/bin/sphinx-quickstart'.
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
- make.bat
A script in the `bin` folder to build the docs::
>>> bin = join(sample_buildout, 'bin')
>>> ls(bin)
- buildout
- sphinx-build
- sphinx-quickstart
- sphinxbuilder
The content of the script is a simple shell script::
>>> script = join(sample_buildout, 'bin', 'sphinxbuilder')
>>> print open(script).read()
cd ...docs
make html
>>> print 'start', system(script)
start /sample-buildout/bin/sphinx-build -b html -d /sample-buildout/docs/doctrees ...src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html
...
If we want `latex`, we need to explicitly define it::
>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
... html
... latex
... """)
>>> print 'start', system(buildout)
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
<BLANKLINE>
Let's see our script now::
>>> cat(script)
cd ...docs
make html
make latex
Finally let's run it::
>>> print 'start', system(script)
start /sample-buildout/bin/sphinx-build -b html -d /sample-buildout/docs/doctrees .../src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html
...
<BLANKLINE>
Build finished. The HTML pages are in /sample-buildout/docs/html.
...
Build finished; the LaTeX files are in /sample-buildout/docs/latex.
Run `make' in that directory to run these through (pdf)latex...
Making output directory...
<BLANKLINE>
If we want `pdf`, we need to explicitly define it::
>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
... html
... latex
... pdf
... """)
>>> print 'start', system(buildout)
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
<BLANKLINE>
Let's see our script now::
>>> cat(script)
cd ...docs
make html
make latex
cd /sample-buildout/docs/latex && make all-pdf
We will skip running the script in tests, because the PDF builder depends
on libraries which may not be installed.
If we want `epub`, like pdf we need to explicitly define it::
>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
... html
... epub
... """)
>>> print 'start', system(buildout)
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
<BLANKLINE>
Let's see our script now::
>>> cat(script)
cd ...docs
make html
make epub
We can also have the script run any doctests in the docs while building::
>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
... doctest
... html
... """)
>>> print 'start', system(buildout)
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
<BLANKLINE>
Let's see our script now::
>>> cat(script)
cd ...docs
make doctest
make html
Again, we will skip running them, this time to avoid a recursive fork bomb. ;)
If we want `extra-paths`, we can define them as normal paths or as unix
wildcards (see `fnmatch` module) ::
>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... extra-paths =
... develop-eggs/
... eggs/*
... """)
>>> print 'start', system(buildout)
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
collective.recipe.sphinxbuilder: inserting extra-paths..
Generated script '/sample-buildout/bin/sphinx-quickstart'.
Generated script '/sample-buildout/bin/sphinx-build'.
<BLANKLINE>
============
Contributors
============
* Tarek Ziade, original author
* Rok Garbas
* Sidnei da Silva
* Hans-Peter Locher
* Domen Kozar
* Tres Seaver
* Sébastien Douche, maintainer
=======
Changes
=======
0.7.1 (2012-04-29):
===================
- Add the epub output.
- Fixed tests:
- Use required package versions during tests
- Use standard `doctest` instead of `zope.testing.doctest`.
0.7.0 (2010-09-10):
===================
- requires Sphinx >= 1.0
0.6.3.3 (2010-07-15)
==========================
- added `doctest` option to recipe's `output` options (tseaver)
- relaxed required version of Sphinx to allow versions later than
0.6.4 (but still less than 0.7dev).
0.6.3.2 (2010-02-08)
====================
- fixed interpreter options [iElectric]
0.6.3.1 (2009-09-25)
====================
- problems with previous release [garbas]
0.6.3 (2009-09-09)
==================
- update to Sphinx 0.6.3 [garbas]
- simplify sphinxbuilder [garbas]
- update documentation [garbas]
- interpreter options [iElectric]
- added logging [iElectric]
0.5.0 (2008-12-06)
==================
- Making it compatible with latest sphinx 0.5 [Rok Garbas]
- Allow for specifying 'product_directories' in order to be able to
document old-style Zope Products. [Sidnei]
0.2.1 (2008-11-18)
==================
- Manifest file fixed and making fix release [Rok Garbas]
0.2.0 (2008-11-11)
==================
- source tree generated every time under
parts/<buildout-section-name> [Rok Garbas]
- finds conf options, source, static and template files using
entry_point 'collective.recipe.sphinxbuilder' [Rok Garbas]
- custom source folder at docs/source [Rok Garbas]
- build section moved to docs/html, docs/latex [Rok Garbas]
0.1.1 (2008-09-11)
==================
- Using a sphinx-build local to the environment [Tarek]
0.1.0 (2008-09-10)
==================
- Initial implementation [Tarek Ziade]
- Created recipe with ZopeSkel [Tarek Ziade].
- Code repository: https://github.com/sdouche/collective.recipe.sphinxbuilder
- Documentation: http:/docs.garbas.si/collective.recipe.sphinxbuilder
- Questions and comments to tarek_at_ziade.org, rok_at_garbas.si, sdouche_at_sdouche.com
Detailed Documentation
**********************
===============
What is Sphinx?
===============
Sphinx is the mainly 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 and many
others
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, PDF or even
epub.
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 =
...
sphinxbuilder
...
[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
source = ${buildout:directory}/docs-source
build = ${buildout:directory}/docs
Run your buildout and you will get a few new scripts in the `bin` folder,
called:
- `sphinx-quickstart`, to quickstart sphinx documentation
- `sphinxbuilder`, script that will
To quickstart a documentation project run, as you would normaly do with Sphinx::
$ bin/sphinx-quickstart
and anwser few questions and choose `docs-source` as you source folder.
To build your documentation, just run the sphinx script::
$ bin/sphinxbuilder
That's it!
You will get a shiny Sphinx documenation in `docs/html`.
Write your documentation, go in `docs-source`.
Everytime source is modified, `sphinxbuilder` run script again.
A good starting point to write your documentation is:
http://sphinx.pocoo.org/contents.html.
=======
Plone 4
=======
Usage with Plone 4 is even easier::
[buildout]
parts =
...
sphinxbuilder
...
[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
interpreter = ${buildout:directory}/bin/zopepy
Follow quick-start tutorial and do not forget to add interpreter with
installed eggs to access your sourcecode with Sphinx.
=================
Supported options
=================
The recipe supports the following options:
build (default: `docs`)
Specify the build documentation root.
source (default: `{build-directory}/source`)
Speficy the source directory of documentation.
outputs (default: `html`)
Multiple-line value that defines what kind of output to produce.
Can be `doctest`, `html`, `latex`, `pdf` or `epub`.
script-name (default: name of buildout section)
The name of the script generated
interpreter
Path to python interpreter to use when invoking sphinx-builder.
extra-paths
Extra paths to be inserted into sys.path.
products
Extra product directories to be extend the Products namespace for
old-style Zope Products.
=============
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 = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... """)
Let's run the buildout::
>>> print 'start', system(buildout)
start Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
Generated script '/sample-buildout/bin/sphinx-quickstart'.
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
- make.bat
A script in the `bin` folder to build the docs::
>>> bin = join(sample_buildout, 'bin')
>>> ls(bin)
- buildout
- sphinx-build
- sphinx-quickstart
- sphinxbuilder
The content of the script is a simple shell script::
>>> script = join(sample_buildout, 'bin', 'sphinxbuilder')
>>> print open(script).read()
cd ...docs
make html
>>> print 'start', system(script)
start /sample-buildout/bin/sphinx-build -b html -d /sample-buildout/docs/doctrees ...src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html
...
If we want `latex`, we need to explicitly define it::
>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
... html
... latex
... """)
>>> print 'start', system(buildout)
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
<BLANKLINE>
Let's see our script now::
>>> cat(script)
cd ...docs
make html
make latex
Finally let's run it::
>>> print 'start', system(script)
start /sample-buildout/bin/sphinx-build -b html -d /sample-buildout/docs/doctrees .../src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html
...
<BLANKLINE>
Build finished. The HTML pages are in /sample-buildout/docs/html.
...
Build finished; the LaTeX files are in /sample-buildout/docs/latex.
Run `make' in that directory to run these through (pdf)latex...
Making output directory...
<BLANKLINE>
If we want `pdf`, we need to explicitly define it::
>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
... html
... latex
... """)
>>> print 'start', system(buildout)
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
<BLANKLINE>
Let's see our script now::
>>> cat(script)
cd ...docs
make html
make latex
cd /sample-buildout/docs/latex && make all-pdf
We will skip running the script in tests, because the PDF builder depends
on libraries which may not be installed.
If we want `epub`, like pdf we need to explicitly define it::
>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
... html
... epub
... """)
>>> print 'start', system(buildout)
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
<BLANKLINE>
Let's see our script now::
>>> cat(script)
cd ...docs
make html
make epub
We can also have the script run any doctests in the docs while building::
>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
... doctest
... html
... """)
>>> print 'start', system(buildout)
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
<BLANKLINE>
Let's see our script now::
>>> cat(script)
cd ...docs
make doctest
make html
Again, we will skip running them, this time to avoid a recursive fork bomb. ;)
If we want `extra-paths`, we can define them as normal paths or as unix
wildcards (see `fnmatch` module) ::
>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... extra-paths =
... develop-eggs/
... eggs/*
... """)
>>> print 'start', system(buildout)
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
collective.recipe.sphinxbuilder: inserting extra-paths..
Generated script '/sample-buildout/bin/sphinx-quickstart'.
Generated script '/sample-buildout/bin/sphinx-build'.
<BLANKLINE>
============
Contributors
============
* Tarek Ziade, original author
* Rok Garbas
* Sidnei da Silva
* Hans-Peter Locher
* Domen Kozar
* Tres Seaver
* Sébastien Douche, maintainer
=======
Changes
=======
0.7.1 (2012-04-29):
===================
- Add the epub output.
- Fixed tests:
- Use required package versions during tests
- Use standard `doctest` instead of `zope.testing.doctest`.
0.7.0 (2010-09-10):
===================
- requires Sphinx >= 1.0
0.6.3.3 (2010-07-15)
==========================
- added `doctest` option to recipe's `output` options (tseaver)
- relaxed required version of Sphinx to allow versions later than
0.6.4 (but still less than 0.7dev).
0.6.3.2 (2010-02-08)
====================
- fixed interpreter options [iElectric]
0.6.3.1 (2009-09-25)
====================
- problems with previous release [garbas]
0.6.3 (2009-09-09)
==================
- update to Sphinx 0.6.3 [garbas]
- simplify sphinxbuilder [garbas]
- update documentation [garbas]
- interpreter options [iElectric]
- added logging [iElectric]
0.5.0 (2008-12-06)
==================
- Making it compatible with latest sphinx 0.5 [Rok Garbas]
- Allow for specifying 'product_directories' in order to be able to
document old-style Zope Products. [Sidnei]
0.2.1 (2008-11-18)
==================
- Manifest file fixed and making fix release [Rok Garbas]
0.2.0 (2008-11-11)
==================
- source tree generated every time under
parts/<buildout-section-name> [Rok Garbas]
- finds conf options, source, static and template files using
entry_point 'collective.recipe.sphinxbuilder' [Rok Garbas]
- custom source folder at docs/source [Rok Garbas]
- build section moved to docs/html, docs/latex [Rok Garbas]
0.1.1 (2008-09-11)
==================
- Using a sphinx-build local to the environment [Tarek]
0.1.0 (2008-09-10)
==================
- Initial implementation [Tarek Ziade]
- Created recipe with ZopeSkel [Tarek Ziade].
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file collective.recipe.sphinxbuilder-0.7.1.tar.gz
.
File metadata
- Download URL: collective.recipe.sphinxbuilder-0.7.1.tar.gz
- Upload date:
- Size: 12.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 674d4c0c69724e632d0bab34ed4fa4f18febf7b7b18965b5e46258e2a7dc6bb0 |
|
MD5 | fab32f9c8ed81c5711566830f0210c83 |
|
BLAKE2b-256 | 0d6307ed73fd430d9df9086e2d25609e45e3c0fd2bd1a761418728776456e6b1 |