/sphinx-substitution-extensions

Extensions for Sphinx which allow substitutions

Primary LanguagePythonApache License 2.0Apache-2.0

Build Status codecov PyPI

Sphinx Substitution Extensions

Extensions for Sphinx which allow substitutions.

Contents

Installation

$ pip install Sphinx-Substitution-Extensions

This supports Python 3.8+.

Setup

  • Add the following to conf.py:
extensions += ['sphinx-prompt', 'sphinx_substitution_extensions']
  • Set the following variable in conf.py:
substitutions = [
    ('|release|', '0.1'),
    ('|author|', 'Eleanor'),
]

This will replace |release| in the new directives with 0.1, and |author| with Eleanor.

Directives

substitution-code-block

.. substitution-code-block:: bash

   echo "|author| released version |release|"

This is an extension of Sphinx's built-in code-block directive, and adds replacement functionality.

substitution-prompt

.. substitution-prompt:: bash

   echo "|author| released version |release|"

This is an extension of sphinx-prompt.

substitution-prompt acts similarly to sphinx-prompt, and adds replacement functionality.

Inline :substitution-code:

:substitution-code:`echo "|author| released version |release|"`

Credits

sphinx-prompt authors

Thanks to @sbrunner and other contributors for sphinx-prompt. substitution-prompt is based on sphinx-prompt.

ClusterHQ Developers

This package is largely inspired by code written for Flocker by ClusterHQ. Developers of the relevant code include, at least, Jon Giddy and Tom Prince.

Contributing

See CONTRIBUTING.rst.