Sphinx/Paver integration
Homepage Repository PyPI Python
pip install sphinxcontrib-paverutils==1.17.0
This module provides an alternative integration of Sphinx and Paver. It supports calling Sphinx from within Paver using multiple configurations, and does not assume you only want to build HTML output.
To use this module, import it in your pavement.py file as from
sphinxcontrib import paverutils
, then define option Bundles for
"html" and/or "pdf" output using the options described in the task
help.
For example:
import paver import paver.misctasks from paver.path import path from paver.easy import * import paver.setuputils paver.setuputils.install_distutils_tasks() try: from sphinxcontrib import paverutils except: import warnings warnings.warn('sphinxcontrib.paverutils was not found, you will not be able to produce documentation') options( setup=Bunch( name = 'MyProject', version = '1.0', # ... more options here ... ), # Defaults for sphinxcontrib.paverutils sphinx = Bunch( docroot='.', sourcedir='docsource', builder='html', ), # One configuration to build HTML for the package html=Bunch( builddir='docs', confdir='sphinx/pkg', ), # Another configuration with different templates # to build HTML to upload to the website website=Bunch( builddir = 'web', confdir='sphinx/web', ), # We also want a PDF file for the website, # so the instructions are included in the web # configuration directory. pdf=Bunch( builddir='web', builder='latex', confdir='sphinx/web', ), )
After you have imported sphinxcontrib.paverutils
in your
pavement.py
file, Paver will show two additional tasks. html
takes the place of the task defined in paver.doctools
and can be
used to build HTML output. pdf
uses the LaTeX builder and an
external toolset such as TeXLive to create a PDF manual.
the root under which Sphinx will be working.
default: docs
directory under the docroot where the resulting files are put.
default: build
directory under the docroot for the source files
default: ""
(empty string)
the location of the cached doctrees
default: $builddir/doctrees
the location of the sphinx conf.py
default: $sourcedir
the location of the generated output files
default: $builddir/$builder
the name of the sphinx builder to use
default: html
dictionary of values to be passed as name-value pairs to the HTML builder
default: {}
You can also develop your own tasks by calling run_sphinx()
directly:
@task @needs(['cog']) @cmdopts([ ('in-file=', 'b', 'Blog input filename'), ('out-file=', 'B', 'Blog output filename'), ]) def blog(options): """Generate the blog post version of the HTML for the current module. """ # Generate html from sphinx paverutils.run_sphinx(options, 'blog') blog_file = path(options.blog.outdir) / options.blog.out_file dry("Write blog post body to %s" % blog_file, gen_blog_post, outdir=options.blog.outdir, input_base=options.blog.in_file, blog_base=options.blog.out_file, ) if 'EDITOR' in os.environ: sh('$EDITOR %s' % blog_file) return
In addition to the html
and pdf
tasks, the package includes the function run_script()
to be used with cog to insert the output of a command line program in your documentation.
This example of reStructuredText source using run_script()
:
.. {{{cog .. cog.out(run_script(cog.inFile, 'anydbm_whichdb.py')) .. }}} .. {{{end}}}
renders to:
.. {{{cog .. cog.out(run_script(cog.inFile, 'anydbm_whichdb.py')) .. }}} :: $ python anydbm_whichdb.py dbhash .. {{{end}}}
The lines prefixed with ..
are comments, and do not appear in the
final HTML or PDF output.
Arguments:
::
prefix is included. When chaining multiple
commands together, the first instance would typically use the default and subsequent
calls would use False.Mode to control how the line breaks are inserted. Options are:
- 'break'
- Insert the newline.
- 'wrap'
- Use the textwrap module to wrap each line individually to the specified width.
- 'fill'
- Use the textwrap module to wrap each line individually, inserting an appropriate amount of whitespace to keep the left edge of the lines aligned.
- 'continue'
- Insert a backslash (
\
) and then a newline to break the line.- 'truncate'
- Break the line at the indicated location and discard the remainder.
Note
PyMOTW makes heavy use of this function, with several variations in arguments, so refer to the source there for more examples if you need them.
Misc.
run_script()
..
.Added simple line-splitting to run_script()
.
Modified run_script()
so that if ignore_error is False any
exception caused by the external application is re-raised. This
"breaks" a build if there is a problem generating the cog output in an
rst file, and makes it easier to spot problems with the cog
instructions.
Updated to include run_script()
function.
First public release based on the versions of these functions developed for PyMOTW.