Doug Hellmann avatar Doug Hellmann committed 39a956e

add run_script function to sphinxcontrib.paverutils

Comments (0)

Files changed (3)

paverutils/README

 ########################
 
 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.
+Sphinx from within Paver using multiple configurations, and does not assume you only want
+to build HTML output.
 
 Basic Usage
 ===========
 docroot
   the root under which Sphinx will be working.
   
-  default: docs
+  default: ``docs``
 
 builddir
   directory under the docroot where the resulting files are put.
 
-  default: build
+  default: ``build``
 
 sourcedir
   directory under the docroot for the source files
 
-  default: (empty string)
+  default: ``""`` (empty string)
 
 doctrees
   the location of the cached doctrees
 
-  default: $builddir/doctrees
+  default: ``$builddir/doctrees``
 
 confdir
   the location of the sphinx conf.py
 
-  default: $sourcedir
+  default: ``$sourcedir``
 
 outdir
   the location of the generated output files
 
-  default: $builddir/$builder
+  default: ``$builddir/$builder``
 
 builder
   the name of the sphinx builder to use
 
-  default: html
+  default: ``html``
 
 template_args
   dictionary of values to be passed as name-value pairs to the HTML builder
 
-  default: {}
+  default: ``{}``
 
 
 Advanced Usage
     @needs(['cog'])
     @cmdopts([
         ('in-file=', 'b', 'Blog input filename'),
-        ('out-file=', 'B', 'Blog output filename'),    
+        ('out-file=', 'B', 'Blog output filename'),
     ])
     def blog(options):
         """Generate the blog post version of the HTML for the current module.
         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, 
+        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,
             )
 
             sh('$EDITOR %s' % blog_file)
         return
 
+
+Cog Extensions
+==============
+
+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:
+
+input_file
+  The name of the file being processed by cog.  Usually passed as cog.inFile.
+
+script_name
+  The name of the Python script living in the same directory as input_file to be run.
+  If not using an interpreter, this can be a complete command line.  If using an
+  alternate interpreter, it can be some other type of file.
+
+include_prefix=True
+  Boolean controlling whether the ``::`` prefix is included. When chaining multiple
+  commands together, the first instance would typically use the default and subsequent
+  calls would use False.
+
+ignore_error=False
+  Boolean controlling whether errors are ignored.  If not ignored, the error
+  is printed to stdout and then the command is run *again* with errors ignored
+  so that the output ends up in the cogged file.
+
+trailing_newlines=True
+  Boolean controlling whether the trailing newlines are added to the output.
+  If False, the output is passed to rstrip() then one newline is added.  If
+  True, newlines are added to the output until it ends in 2.
+
+
+
+
+.. 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.
+
 Users
 =====
 
 .. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper/
 
 .. _TeXLive: http://tug.org/texlive/
+
+
+History
+=======
+
+1.1
+---
+
+Updated to include ``run_script()`` function.
+
+1.0
+---
+
+First public release based on the versions of these functions developed for PyMOTW_.

paverutils/setup.py

 requires = ['Sphinx>=0.6', 'Paver>=1.0.1']
 
 NAME='sphinxcontrib-paverutils'
-VERSION='1.0'
+VERSION='1.1'
 
 setup(
     name=NAME,

paverutils/sphinxcontrib/paverutils.py

     doctrees.mkdir()
 
     return Bunch(locals())
+
+
+def run_script(input_file, script_name, 
+                interpreter='python',
+                include_prefix=True, 
+                ignore_error=False, 
+                trailing_newlines=True,
+                ):
+    """Run a script in the context of the input_file's directory, 
+    return the text output formatted to be included as an rst
+    literal text block.
+    
+    Arguments:
+    
+     input_file
+       The name of the file being processed by cog.  Usually passed as cog.inFile.
+     
+     script_name
+       The name of the Python script living in the same directory as input_file to be run.
+       If not using an interpreter, this can be a complete command line.  If using an
+       alternate interpreter, it can be some other type of file.
+     
+     include_prefix=True
+       Boolean controlling whether the :: prefix is included.
+     
+     ignore_error=False
+       Boolean controlling whether errors are ignored.  If not ignored, the error
+       is printed to stdout and then the command is run *again* with errors ignored
+       so that the output ends up in the cogged file.
+     
+     trailing_newlines=True
+       Boolean controlling whether the trailing newlines are added to the output.
+       If False, the output is passed to rstrip() then one newline is added.  If
+       True, newlines are added to the output until it ends in 2.
+    """
+    rundir = path(input_file).dirname()
+    if interpreter:
+        cmd = '%(interpreter)s %(script_name)s' % vars()
+    else:
+        cmd = script_name
+    real_cmd = 'cd %(rundir)s; %(cmd)s 2>&1' % vars()
+    try:
+        output_text = sh(real_cmd, capture=True, ignore_error=ignore_error)
+    except Exception, err:
+        print '*' * 50
+        print 'ERROR run_script(%s) => %s' % (real_cmd, err)
+        print '*' * 50
+        output_text = sh(real_cmd, capture=True, ignore_error=True)
+        print output_text
+        print '*' * 50
+    if include_prefix:
+        response = '\n::\n\n'
+    else:
+        response = ''
+    response += '\t$ %(cmd)s\n\t' % vars()
+    response += '\n\t'.join(output_text.splitlines())
+    if trailing_newlines:
+        while not response.endswith('\n\n'):
+            response += '\n'
+    else:
+        response = response.rstrip()
+        response += '\n'
+    return response
+
+# Stuff commonly used symbols into the builtins so we don't have to
+# import them in all of the cog blocks where we want to use them.
+__builtins__['run_script'] = run_script
+#__builtins__['sh'] = sh
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.