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