Documentation Markup

There home-grown special markup syntax you can use in the documentation. It is kind of a mixture of XML, LaTeX, Python doctest, and custom markup.

In the future, we plan to use more Sphinx-based documentation.

The following commands can be used to markup documentation text:

Markup in Documentation



<dl> dl-list </dl>

a definition list with <dt> and <dd> entries.

<dt> title

the title of a description item.

<dd> description

the description of a description item.

<ul> list </ul>

an unordered list of <li> entries.

<ol> list </ol>

an ordered list of <li> entries.

<li> item

an item of an unordered or ordered list. Note: no </li>.

' code '

inline Mathics code or other code.

$ name $

Math-mode variable identifier in Mathics code or in text.

<console> text </console>

a console (shell/bash/Terminal) transcript in its own paragraph.

<con> text </con>

an inline console transcript.

<em> text </em>

emphasized (italic) text.

<i> text </i>

the same as <em>.

<url> url </url>

a URL.

<url> :link text: url </url>

a URL with link text

<img src=" src " title=" title " label=" label "

an image.

<imgpng src=" srctitle=" title " label=" label "

the same as <img>.

<ref label=” label “>``

a reference to an image.


a vertical skip.

\LaTeX, \Mathematica, \Mathics

special product and company names.


a single '.

## $comment$

a comment line that is not shown in the documentation.

To include images in the documentation, use the img tag, place an EPS file src .eps in mathics.doc.documentation.images and run in the mathics.doc directory.

Markup for Code Examples

The following commands can be used to specify test cases.



>> Mathics code

Some Mathics code to run and to appear in documentation.

= output

expected output produced by the Mathics code.


matches any output; used when output can vary.


a newline which is expected to appear in test output.


graphics in the test result.

: message

a message in the result of the test query.

\| print

a printed line in the result of the test query.

It is good to create examples that convey some aspect about the Mathics Function.

In the past, the documentation system was abused and ran edge cases and prior bugs fixed. For that please write a pytest.

We have not purged ourself of this behavior, so will find following markup in docstrings. These are deprecated.

However please don’t create more examples. Instead please consider moving something like this to a pytest unit test which is far more flexibile.



#> Mathics code

Some Mathics code to run but not appearing documentation.

X> Mathics code

Mathics code shown in the documentation but not run.


a test query that is shown in the documentation and run

Todo: give examples of each of these.