.. default-domain:: rst
.. highlight:: rest

:py:mod:`lunar.sphinx.ext.programoutput` -- Include program output
==================================================================

.. py:module:: lunar.sphinx.ext.programoutput
   :synopsis:  Include the output of programs into documents


This extension allows you to run programs during the build process, and
include their output into the documentation.

It adds this main directive:

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

   .. program-output:: python -V

   However, special shell features like parameter expansion are not
   supported::

      .. program-output:: echo "$USER"

   .. program-output:: echo "$USER"

   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:

   .. program-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.

   You can include the command, which produced the output, by specified
   option ``prompt``.  The result will mimic input on a shell prompt with
   the resulting output::

      .. program-output:: python -V
         :prompt:

   .. program-output:: python -V
      :prompt:

   The prompt can be configured using
   :confval:`programoutput_prompt_template`.  The directive
   :dir:`command-output` provides a convenient shortcut to this directive
   with ``prompt``.

   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.

   You can shorten the output of programs 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 ``...``::

      .. program-output::  python --help
         :prompt:
         :ellipsis: 2

   .. program-output::  python --help
      :prompt:
      :ellipsis: 2

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

      .. program-output::  python --help
         :prompt:
         :shell:
         :ellipsis: 2, -2

   .. program-output::  python --help
      :prompt:
      :shell:
      :ellipsis: 2, -2


.. directive:: command-output

   Just like :dir:`program-output`, but with ``prompt`` enabled.


Configuration
-------------

This extension understands the following configuration options:

.. confval:: programoutput_prompt_template

   This configuration value defines the looks of the output of
   :dir:`command-output` and :dir:`program-output` with option ``prompt``.
   The default value is ``$ %(command)s\n%(output)s``.  The key ``command``
   is replaced with the command, the key ``output`` with the output of this
   command.

.. confval:: programoutput_use_ansi

   Interpret ANSI colour sequences in program output.  The extension
   :py:mod:`lunar.sphinx.ext.ansi` must be enabled and configuration for
   this to work properly.