Commits

Sebastian Wiesner  committed c0fbf72

Reworked, updated and improved documentation, Python 2.6 required now

  • Participants
  • Parent commits 7e0958f

Comments (0)

Files changed (4)

File programoutput/CHANGES.rst

 0.5 (in development)
 ====================
 
+- Require Python 2.6 now
 - Warn on unexpected return codes instead of raising
   :exc:`~subprocess.CalledProcessError`
 

File programoutput/README

 
 http://packages.python.org/sphinxcontrib-programoutput
 
-This Sphinx_ 1.0 extension executes programs during the build step and
-includes their output into the documentation.  It supports the
-`sphinxcontrib-ansi`_ extension to turn colored output of programs in
-pretty-formatted HTML.
+Sphinx 1.0 extension to insert the output of arbitrary commands into documents.
+
+The extension is available under the terms of the BSD license, see LICENSE_ for
+details.
 
 
 Installation
 ------------
 
-This extension can be installed from the Python Package Index::
+This extension requires Sphinx_ 1.0 and Python 2.6.  It is available in the
+Python Package Index::
 
    pip install sphinxcontrib-programoutput
 
 Alternatively, you can clone the sphinx-contrib_ repository from BitBucket,
 and install the extension directly from the repository::
 
-   hg clone http://bitbucket.org/birkenfeld/sphinx-contrib
+   hg clone https://bitbucket.org/birkenfeld/sphinx-contrib
    cd sphinx-contrib/programoutput
    python setup.py install
 
 
 
 .. _`Sphinx`: http://sphinx.pocoo.org/latest
-.. _`sphinxcontrib-ansi`: http://packages.python.org/sphinxcontrib-ansi
-.. _`sphinx-contrib`: http://bitbucket.org/birkenfeld/sphinx-contrib
+.. _`sphinx-contrib`: https://bitbucket.org/birkenfeld/sphinx-contrib
 .. _documentation: http://packages.python.org/sphinxcontrib-programoutput
+.. _LICENSE: https://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/LICENSE

File programoutput/doc/conf.py

 
 needs_sphinx = '1.0'
 
-extensions = ['sphinx.ext.intersphinx',
-              'sphinxcontrib.programoutput']
+extensions = ['sphinx.ext.intersphinx', 'sphinxcontrib.programoutput']
 
 source_suffix = '.rst'
 master_doc = 'index'
 html_static_path = []
 
 intersphinx_mapping = {
+    'python': ('http://docs.python.org', None),
     'ansi': ('http://packages.python.org/sphinxcontrib-ansi', None)}
 
 

File programoutput/doc/index.rst

 .. default-domain:: rst
 .. highlight:: rest
 
-:py:mod:`sphinxcontrib.programoutput` -- Include program output
-==================================================================
+:py:mod:`sphinxcontrib.programoutput` – Insert command output
+=============================================================
 
 .. py:module:: sphinxcontrib.programoutput
    :synopsis:  Include the output of programs into documents
 
-This extension for Sphinx_ 1.0 allows to run programs during the build
-process, including their output into the documentation.  It supports the
-:py:mod:`sphinxcontrib.ansi` extension to turn colored output of programs in
-pretty-formatted HTML.
+Sphinx 1.0 extension to insert the output of arbitrary commands into documents.
 
 The extension is available under the terms of the BSD license, see LICENSE_
 for more information.
 Installation
 ------------
 
-This extension can be installed from the Python Package Index::
+This extension requires Sphinx_ 1.0 and Python 2.6.  It is available in the
+Python Package Index::
 
    pip install sphinxcontrib-programoutput
 
 Alternatively, you can clone the sphinx-contrib_ repository from BitBucket,
 and install the extension directly from the repository::
 
-   hg clone http://bitbucket.org/birkenfeld/sphinx-contrib
+   hg clone https://bitbucket.org/birkenfeld/sphinx-contrib
    cd sphinx-contrib/programoutput
    python setup.py install
 
 Usage
 -----
 
-The main directive is :dir:`program-output`:
-
-.. directive:: program-output
-
-   This directive accepts a single string as argument, which is the command
-   to execute.  By default, this command string is split using the
-   :py:mod:`shlex` modules, which mostly works like common Unix shells like
-   ``bash`` or ``zsh``::
-
-      .. program-output:: python -V
-
-   The above snippet would render like this:
+To include the output of a command into your document, use the
+:dir:`program-output` directive provided by this extension::
 
    .. program-output:: python -V
 
-   However, special shell features like parameter expansion are not
-   supported::
+The whole output of ``python -V``, including any messages on standard error, is
+inserted into the current document, formatted as literal text without any
+syntax highlighting:
 
-      .. program-output:: echo "$USER"
+.. program-output:: python -V
 
-   .. program-output:: echo "$USER"
+You can omit the content of the standard error stream with the ``nostderr``
+option.
 
-   To enable such shell features, use option ``shell``.  If this option is
-   given, the command string is executed using ``/bin/sh -c``::
 
-      .. program-output:: echo "$USER"
-         :shell:
+Shortening the output
+^^^^^^^^^^^^^^^^^^^^^
 
-   .. program-output:: echo "$USER"
+Lengthy output can be shortened with the ``ellipsis`` option.  Its value
+denotes lines to omit when inserting the output of the command.  Instead, a
+single ellipsis ``...`` is inserted.
+
+If used with a single number, all lines after the specified line are omitted::
+
+   .. program-output:: python --help
+      :ellipsis: 2
+
+The above omits all lines after the second one:
+
+.. program-output:: python --help
+   :ellipsis: 2
+
+Negative numbers count from the last line backwards, thus replacing ``2`` with
+``-2`` in the above example would only omit the last two lines.
+
+If used with two comma-separated line numbers, all lines in between the
+specified lines are omitted.  Again, a negative number counts from the last
+line backwards::
+
+   .. program-output:: python --help
+      :ellipsis: 2,-2
+
+The above omits all lines except the first two and the last two lines:
+
+.. program-output:: python --help
+   :ellipsis: 2,-2
+
+
+Mimicing shell input
+^^^^^^^^^^^^^^^^^^^^
+
+You can mimic shell input with the :dir:`command-output` directive [#alias]_.
+This directive inserts the command along with its output into the document::
+
+   .. command-output:: python -V
+
+.. command-output:: python -V
+
+The appearance of this output can be configured with
+:confval:`programoutput_prompt_template`.  When used in conjunction with
+``ellipsis``, the command itself and any additional text is *never* omitted.
+``ellipsis`` always refers to the *immediate output* of the command::
+
+   .. command-output:: python --help
+      :ellipsis: 2
+
+.. command-output:: python --help
+   :ellipsis: 2
+
+
+Command execution and shell expansion
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Normally the command is splitted according to the POSIX shell syntax (see
+:py:mod:`shlex`), and executed directly.  Thus special shell features like
+expansion of environment variables will not work::
+
+   .. command-output:: echo "$USER"
+
+.. command-output:: echo "$USER"
+
+To enable these features, enable the ``shell`` option.  With this option, the
+command is literally passed to the system shell::
+
+   .. command-output:: echo "$USER"
       :shell:
 
-   By default, both standard output *and* standard error are captured and
-   included in the document.  Use option ``nostderr`` to hide anything from
-   the standard error stream of the invoked program.
+.. command-output:: echo "$USER"
+   :shell:
 
-   Using the option ``prompt`` you can include the command, that produced
-   the output.  The result will mimic input on a shell prompt with the
-   resulting output::
+Other shell features like process expansion consequently work, too::
 
-      .. program-output:: python -V
-         :prompt:
+   .. command-output:: ls -l $(which grep)
+      :shell:
 
-   .. program-output:: python -V
-      :prompt:
+.. command-output:: ls -l $(which grep)
+   :shell:
 
-   The prompt can be configured using
-   :confval:`programoutput_prompt_template`.  The directive
-   :dir:`command-output` provides a convenient shortcut to this directive
-   with ``prompt``.
+Remember to use ``shell`` carefully to avoid unintented interpretation of shell
+syntax!
 
-   Sometimes the program may require options, you may not want to include in
-   the prompt.  You can use the ``extraargs`` option for this purpose.  The
-   value of this options is parsed just like the command itself, and
-   afterwards appended to the command.  It will however never appear in the
-   output, if ``prompt`` is specified.
 
-   Lengthy output can be shortened using the ``ellipsis`` option.  This
-   option accepts at most two comma-separated integers, which refer to lines
-   in the output.  If the second integer is missing, it refers to the last
-   line.  Everything in between these lines is replaced by a single ellipsis
-   ``...``::
+Reference
+---------
 
-      .. program-output::  python --help
-         :prompt:
-         :ellipsis: 2
+.. directive:: .. program-output:: command
 
-   .. program-output::  python --help
-      :prompt:
-      :ellipsis: 2
+   Include the output of ``command`` in the documentation.
 
-   Negative line numbers are counted from the last-line.  Thus specifying
-   ``:ellipsis:  2, -2`` will remove anything except the first two and the
-   last two lines::
+   The output is formatted as literal text, without any syntax highlighting.
 
-      .. program-output::  python --help
-         :prompt:
-         :shell:
-         :ellipsis: 2, -2
+   By default, the command is split according to the POSIX shell syntax (using
+   :py:func:`shlex.split()`), and executed directly.  Both standard output and
+   standard error are captured from the invocation of ``command`` and included
+   in the document.  However, if the option ``shell`` is given, ``command`` is
+   literally passed to the system shell.  With the ``nostderr`` option,
+   standard error is hidden from the output.
 
-   .. program-output::  python --help
-      :prompt:
-      :shell:
-      :ellipsis: 2, -2
+   If the ``prompt`` option is given, the ``command`` itself is included in the
+   document, so that the output mimics input in a shell prompt.
+   :confval:`programoutput_prompt_template` controlls the appearance of this.
+   The value of the ``extraargs`` option is appended at the end of ``command``
+   (separated by a whitespace) before executing the command, but not included
+   in the output of the ``prompt`` option.  Use this to pass extra arguments
+   which should not appear in the document.
 
+   The output can be shortened with the ``ellipsis`` option.  The value of this
+   option is of the form ``start[,end]`` with ``start`` and ``end`` being
+   integers which refer to lines in the output of ``command``.  ``end`` is
+   optional and defaults to the last line.  Negative line numbers count
+   backwards from the last line.  Everything in the interval ``[start, end[``
+   is replaced with a single ellipsis ``...``.  The ``ellipsis`` option only
+   affects the immediate output of ``command``, but never any additional text
+   inserted by option ``prompt``.
 
 .. directive:: command-output
 
-   Just like :dir:`program-output`, but with ``prompt`` enabled.
+   Same as :dir:`program-output`, but with enabled ``prompt`` option.
 
 
 Configuration
    and configured.  If missing or ``False``, these sequences are not
    interpreted, but appear in documentation unchanged.
 
+
 Contribution
 ------------
 
 functionality (e.g. integration of some other issue tracker).  Patches are
 welcome!
 
+.. rubric:: Footnotes
+
+.. [#alias] This directive is just an alias for the :dir:`program-output`
+            directive with the ``prompt`` option set.
 
 .. toctree::
    :maxdepth: 2
 
 
 .. _`Sphinx`: http://sphinx.pocoo.org/
-.. _`sphinx-contrib`: http://bitbucket.org/birkenfeld/sphinx-contrib
-.. _`issue tracker`: http://bitbucket.org/birkenfeld/sphinx-contrib/issues
-.. _LICENSE: http://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/LICENSE
+.. _`sphinx-contrib`: https://bitbucket.org/birkenfeld/sphinx-contrib
+.. _`issue tracker`: https://bitbucket.org/birkenfeld/sphinx-contrib/issues
+.. _LICENSE: https://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/LICENSE