Source

########################
sphinxcontrib.paverutils
########################
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.
Basic Usage
===========
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',
),
)
Tasks
=====
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.
Configuration Parameters
========================
docroot
the root under which Sphinx will be working.
default: docs
builddir
directory under the docroot where the resulting files are put.
default: build
sourcedir
directory under the docroot for the source files
default: (empty string)
doctrees
the location of the cached doctrees
default: $builddir/doctrees
confdir
the location of the sphinx conf.py
default: $sourcedir
outdir
the location of the generated output files
default: $builddir/$builder
builder
the name of the sphinx builder to use
default: html
template_args
dictionary of values to be passed as name-value pairs to the HTML builder
default: {}
Advanced Usage
==============
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
Users
=====
PyMOTW_
The Python Module of the Week package is built using Paver and Sphinx, including three forms of HTML and a PDF.
virtualenvwrapper_
The documentation for virtualenvwrapper includes the packaged HTML and a website using alternate templates.
.. _Paver: http://www.blueskyonmars.com/projects/paver/
.. _PyMOTW: http://www.doughellmann.com/PyMOTW/
.. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper/
.. _TeXLive: http://tug.org/texlive/