The Sage Manuals#

Sage’s manuals are written in ReST (reStructuredText), and generated with the software Sphinx:

Name

Files

Tutorial

SAGE_ROOT/src/doc/en/tutorial

Developer’s guide

SAGE_ROOT/src/doc/en/developer

Constructions

SAGE_ROOT/src/doc/en/constructions

Installation guide

SAGE_ROOT/src/doc/en/installation

Reference manual

SAGE_ROOT/src/doc/en/reference (most of it is generated from the source code)

  • Additionally, more specialized manuals can be found under SAGE_ROOT/src/doc/en.

  • Some documents have been translated into other languages. In order to access them, change en/ into fr/,es/, de/… See Document names.

Editing the documentation#

After modifying some files in the Sage tutorial (SAGE_ROOT/src/doc/en/tutorial/), you will want to visualize the result. In order to build a html version of this document, type:

sage --docbuild tutorial html

You can now open SAGE_ROOT/local/share/doc/sage/html/en/tutorial/index.html in your web browser.

Run doctests: All files must pass tests. After modifying a document (e.g. tutorial), you can run tests with the following command (see Running automated doctests):

sage -tp SAGE_ROOT/src/doc/en/tutorial/

Reference manual: as this manual is mostly generated from Sage’s source code, you will need to build Sage in order to see the changes you made to some function’s documentation. Type:

sage -b && sage --docbuild reference html

Adding a new file#

If you added a new file to Sage (e.g. sage/matroids/my_algorithm.py) and you want its content to appear in the reference manual, you have to add its name to the file SAGE_ROOT/src/doc/en/reference/matroids/index.rst. Replace ‘matroids’ with whatever fits your case.

The combinat/ folder: if your new file belongs to a subdirectory of combinat/ the procedure is different:

  • Add your file to the index stored in the __init__.py file located in the directory that contains your file.

  • Add your file to the index contained in SAGE_ROOT/src/doc/en/reference/combinat/module_list.rst.

Making portions of the reference manual conditional on optional features#

For every dynamically detectable feature such as graphviz or sage.symbolic (see sage.features), Sage defines a Sphinx tag that can be used with the Sphinx directive “.. ONLY::”. Because Sphinx tags have to use Python identifier syntax, Sage uses the format feature_, followed by the feature name where dots are replaced by underscores. Hence, conditionalizing on the features of the previous examples would look as follows:

.. ONLY:: feature_graphviz

and:

.. ONLY:: feature_sage_symbolic

Building the manuals#

(Do you want to edit the documentation? Click here)

All of the Sage manuals are built using the sage --docbuild script. The content of the sage --docbuild script is defined in SAGE_ROOT/src/sage_docbuild/__init__.py. It is a thin wrapper around the sphinx-build script which does all of the real work. It is designed to be a replacement for the default Makefiles generated by the sphinx-quickstart script. The general form of the command is:

sage --docbuild <document-name> <format>

For example:

sage --docbuild reference html

Two help commands which give plenty of documentation for the sage --docbuild script:

sage --docbuild -h # short help message
sage --docbuild -H # a more comprehensive one

Output formats: All output formats supported by Sphinx (e.g. pdf) can be used in Sage. See http://www.sphinx-doc.org/builders.html.

Broken links: in order to build the documentation while reporting the broken links that it contains, use the --warn-links flag. Note that Sphinx will not rebuild a document that has not been updated, and thus not report its broken links:

sage --docbuild --warn-links reference html

Document names#

The <document-name> has the form:

lang/name

where lang is a two-letter language code, and name is the descriptive name of the document. If the language is not specified, then it defaults to English (en). The following two commands do the exact same thing:

sage --docbuild tutorial html
sage --docbuild en/tutorial html

To specify the French version of the tutorial, you would simply run:

sage --docbuild fr/tutorial html

Syntax highlighting Cython code#

If you want to write Cython code in a ReST file, precede the code block by .. CODE-BLOCK:: cython instead of the usual ::. Enable syntax-highlighting in a whole file with .. HIGHLIGHT:: cython. Example:

cdef extern from "descrobject.h":
    ctypedef struct PyMethodDef:
        void *ml_meth
    ctypedef struct PyMethodDescrObject:
        PyMethodDef *d_method
    void* PyCFunction_GET_FUNCTION(object)
    bint PyCFunction_Check(object)