Skip to content
Branch: master
Go to file
Code

Latest commit

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.rst

Description of the Theorem Sphinx Extension

This extension to Sphinx 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.


Version:1.1
Author:Roland Puntaier roland.puntaier@gmail.com
License:BSD License
Git Repository:https://github.com/rpuntaie/sphinxcontrib-thm
PyPI Package:http://pypi.python.org/pypi/sphinxcontrib-thm

Prerequisites and Configuration

This Sphinx extension must be installed. Use:

pip install sphinxcontrib-thm

This takes it from PyPI.

To install it from the github repository:

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 dist/sphinxcontrib-thm*tar.gz

or:

pip install 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 probably be in conf.py, because this extension is aimed at math authoring with Sphinx, but it is not a requirement.

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. They can only contain text, no 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 formating via css. This can be done using conf.py.

Here is an example conf.py:

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

About

No description, website, or topics provided.

Resources

License

Releases

No releases published
You can’t perform that action at this time.