sphinxcontrib-paverutils 1.0

Sphinx/Paver integration

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.