Doug Hellmann avatar Doug Hellmann committed bb1d543

update paverutils docs

Comments (0)

Files changed (3)

paverutils/README

 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',
+        ),
+
+    )
+
+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/

paverutils/setup.py

 
 from setuptools import setup, find_packages
 
-long_desc = '''
+try:
+    long_desc = open('README', 'r').read()
+except IOError:
+    long_desc = '''
 This package contains an alternative integration of Sphinx and Paver allowing for both HTML and PDF generation from the same pavement.py file.
 '''
 

paverutils/sphinxcontrib/paverutils.py

 """Alternative integration of Sphinx and Paver.
 
 To use this module, import it in your pavement.py file as 
-``from sphinxcontrib import docpaver``,  then define 
+``from sphinxcontrib import paverutils``,  then define 
 option Bundles for "html" and/or "pdf" output using the options
 described in the task help.
 
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.