Archived

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.

Prerequisites and Configuration

To install, use:

pip install sphinxcontrib-thm

To install directly from github:

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

or:

pip install --user git+https://github.com/rpuntaie/sphinxcontrib-thm

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 conf.py.

You have to load the extension in conf.py:

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

Usage

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 conf.py 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 conf.py.

Here is an example conf.py:

.. literalinclude:: ../test/conf.py
   :language: python