docutils_shell

Overview

This package defines the shell directive, a Docutils extension which can insert the output of any shell command into your restructered text markup.

Installation

From PyPi

$ pip install docutils-shell

From source

$ hg clone ssh://hg@bitbucket.org/pwexler/docutils_shell
$ pip install -e docutils_shell/

The installation is successful if you can import docutils_shell. The following command must produce no errors:

$ python -c 'import docutils_shell'

Usage

rst markup

In your .rst, include each shell directive just once to fetch and store its data. Use the appropriate substitution tags to insert the stored data wherever it is needed.

For example, this markup:

Version |VERSION| Revision |REVISION|, |TIMESTAMP|

.. shell:: python setup.py --version
           VERSION

.. shell:: hg parent --template {rev}
           REVISION

.. shell:: date "+built on %a %d %b %Y at %X %Z"
           TIMESTAMP

Looks like this:

Version 0.0.2 Revision 11, built on Mon 15 Jun 2015 at 05:19:31 PM EDT

Each command’s standard output is stored in the given tag. The tag’s value is fetched using |tag|, docutils’ replacement syntax.

Note that arguments are passed to all docutils directives as words; and the shell directive takes the last word as the tag. For example:

.. shell:: echo word1 word2
           word3
           WORDS

|WORDS|

Yields:

word1 word2 word3

Each command is run in its own shell with the current directory set to the project base.

You may run any valid shell command, so for example, if you are using github and you want to store git’s version hash in REVISION:

.. shell:: git log -1 | head -1 | cut -c8-
           REVISION

Settings

docutils_shell.SETTINGS contains program settings which may be changed directly in conf.py

project_base

default: .

Use this to set an absolute address for the project base whenever it is not the current directory.

conf.py

Ordinarily, builds are run from the project’s base directory:

python setup.py build_sphinx

However in build environments where this is not the case you must tell docutils_shell where the project’s base directory is.

This is easily done in conf.py using Python’s built-in __file__ attribute and os.path methods. For example if conf.py is in doc/ relative to the project base then in conf.py:

import docutils_shell
import os

docutils_shell.SETTINGS['project_base'] = os.path.abspath(
        os.path.dirname(
                os.path.dirname(__file__)))