sphinx-contrib / paverutils /

Filename Size Date modified Message
..
sphinxcontrib
1.3 KB
49 B
4.2 KB
97 B
1.3 KB
########################
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/
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.