Skip to main content

Sphinx extension for directives mentioned in amsthm (theorem, example, exercise,...) and more

Project description


Possibly since this Sphinx 3.3 automatic numbering of this Sphinx extension, and :numref:, does not work any more.

Alternative: Sphinx-proof.

Description of the Theorem Sphinx Extension

This Sphinx extension adds directives mentioned in the LaTeX amsthm package: theorem, example, exercise,…and more.

Sphinx has no directive that would well fit such items.

For LaTeX these are translated to \begin{theorem}{title} and so on.




Roland Puntaier


BSD License

Git Repository:

PyPI Package:

Prerequisites and Configuration

To install, use:

pip install sphinxcontrib-thm

To install directly from github:

git clone
cd sphinxcontrib-thm
#don't use install here! It would produce a second sphinxcontrib folder
python sdist
pip install --user dist/sphinxcontrib-thm*tar.gz


pip install --user git+

For LaTeX output, amsthm (or ntheorem) is needed. For the example in the test folder also unicode-math is needed.

For HTML output, sphinx.ext.mathjax should be in

You have to load the extension in

extensions = ['sphinxcontrib.thm',``sphinx.ext.mathjax``,...]


The extension adds

  • several directives mentioned in amsthm:

    .. theorem:: title
    .. lemma:: title
    .. corollary:: title
    .. proposition:: title
    .. conjecture:: title
    .. criterion:: title
    .. assertion:: title
    .. definition:: title
    .. condition:: title
    .. problem:: title
    .. example:: title
    .. exercise:: title
    .. algorithm:: title
    .. question:: title
    .. axiom:: title
    .. property:: title
    .. assumption:: title
    .. hypothesis:: title
    .. remark:: title
    .. notation:: title
    .. claim:: title
    .. summary:: title
    .. acknowledgment:: title
    .. case:: title
    .. conclusion:: title
    .. proof:: title

    For LaTeX, you need to separately define these in via \newtheorem in the LaTeX preamble. See below.

    While .. note:: and others use \begin{sphinxadmonition}{title}, these directives are translated to \begin{theorem}{title} and so on.

  • environment directive:

    .. environment:: instruction
        :name: Instruction
        :html_title: title used by html builder
        :latex_title: title used by LaTeX builder

    You can also use :title: if both :html_title: and :latex_title: should to be the same. Replace instruction. It is a mandatory argument. In LaTeX you must have newtheorem{instruction}{Instruction}, unless it is an available LaTeX environment, like equation.

  • textcolor directive and role:

    .. textcolor:: #00FF00
            This text is green
    :textcolor:`<#FF0000> this text is red`.

    Roles are not recursive. Rolse can only contain text, not other nodes. Directives are recursive, though.

  • align directive:

    .. align:: center
    .. align:: left
    .. align:: flushleft
    .. align:: right
    .. align:: flushright

    Each of them has a separate numbering.

For refs use the normal sphinx refs like:

.. _`theorem1`:

.. theorem:: title

Text here: By using backticks one can find the matching parts more easily in the editor.

See `theorem1`_.

In HTML one needs to provide formatting via css. This can be done using

Here is an example

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page