==============
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:

.. parsed-literal::

    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

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:

.. shell:: echo word1 word2 
           word3
           WORDS

.. parsed-literal::

    |WORDS|


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__)))