The Sage Manuals

This chapter describes how to modify the Sage manuals. Sage’s manuals are written in ReST, otherwise known as reStructuredText. To edit them, you just need to edit the appropriate file. The documentation builder is called Sphinx.

Here is a list of the Sage manuals and the corresponding files to edit:

  • The Sage tutorial: SAGE_ROOT/devel/sage/doc/en/tutorial
  • The Sage developer’s guide: SAGE_ROOT/devel/sage/doc/en/developer
  • Constructions in Sage: SAGE_ROOT/devel/sage/doc/en/constructions
  • The Sage installation guide: SAGE_ROOT/devel/sage/doc/en/installation
  • The Sage reference manual: some of this is contained in the file SAGE_ROOT/devel/sage/doc/en/reference, but most of it is automatically generated from the Sage source code.
  • Additional, more specialized manuals can be found under SAGE_ROOT/devel/sage/doc/en as well.

Note

You can edit manuals that have been translated into another language by replacing the en/ above with the appropriate two letter language code. For example, the French tutorial is located in SAGE_ROOT/devel/sage/doc/fr/tutorial

Editing the manuals

If, for example, you want to change the Sage tutorial, then you should start by modifying the files in SAGE_ROOT/devel/sage/doc/en/tutorial/. Then to build a PDF file with your changes, type:

sage --docbuild tutorial pdf

You will get a file tutorial.pdf in SAGE_ROOT/devel/sage/doc/output/pdf/en/tutorial which you should inspect. You can build the HTML version of the tutorial by typing:

sage --docbuild tutorial html

Once you have done this, you can access the new HTML version from the notebook interface to Sage by clicking the Help link, or you can open the file SAGE_ROOT/devel/sage/doc/output/html/en/tutorial/index.html in your web browser. For more detailed information about building the documentation, see Building the manuals.

You should also run

sage -tp 1 SAGE_ROOT/devel/sage/doc/en/tutorial/

to test all of the examples in the tutorial, see Automated testing for more details.

Finally, you might want to share your changes with the Sage community. To do this, use Mercurial (see Producing Patches with Mercurial) to produce patch files, and submit them to the Sage trac server.

As noted above, the reference manual is mostly autogenerated from Sage source code. To build it, type:

sage -b <repo-name>
sage --docbuild reference <format>

where <repo-name> is the name of the repository you are using, and <format> is html, pdf, or any other supported format (as listed when you run sage --docbuild --formats).

Linking to modules, classes, methods, ..., trac tickets and Wikipedia

For full documentation, refer to inline markup in the Sphinx documentation. Currently, there is no support for defining chapters and labels in the autogenerated documentation. However, it is possible to generate a link to the documentation for any module, class, method, function, etc. The syntax is

:role:`title <target>`

or

:role:`target`

where

  • role is the kind of thing you want to link to (i.e. mod for module, class for classes, meth for methods, func for functions, etc;
  • target is the Python name of the object (class, module, method, etc.) which carries the documentation to be linked to;
  • title is the name of the link as shown in the browser.

If you do not provide any title then target will be used. For example, to link to the dyck_word module, you would use :mod:`sage.combinat.dyck_word` or if you prefer :mod:`Dyck words<sage.combinat.dyck_word>`. Note that, in the first case, the full qualified Python address is used which is usually too long. You can prefix it with a "~" to get only the final name. For example, in the huge link

:meth:`~sage.combinat.non_decreasing_parking_function.NonDecreasingParkingFunction.to_dyck_word`

only ".to_dyck_word()" will appear. Note that the parentheses in the link are autogenerated.

Local names are handled. That is, for example, in the definition of a class (and any of its members or methods), you can link to any member or method of the same class by simply giving the name of it prepended by a dot ".". You do not need to give its full address. For example:

:meth:`.to_dyck_word`

sets up a link to the .to_dyck_word() method of the current class if it exists. If not, the documentation builder searches by going up in the class/module hierarchy of Python until it finds an object with this name or reaches the top-level module without finding it. If the name cannot be found, the title is typeset in boldface without any link produced and also without any error or warning. Note that without the prepended dot, the object is searched starting from the top-level to the innermost module or class.

You can also link, without giving the full path, to objects imported in a local module or imported by default in Sage. For example, the two following are equivalent, as Parent is imported by default in Sage (using the all.py files):

:class:`Parent`
:class:`~sage.structure.parent.Parent`

Sage adds a special role to link to trac ticket. The code :trac:`12490` link to the trac ticket #12490. When fixing a bug, you should add the link to the corresponding trac ticket in the TEST section. Here is an example:

TEST:

We check for :trac:`5534`::

    sage: w = ["a", "b", "c", "d"]; ww = ["b", "d"]
    sage: x = sage.combinat.subword.smallest_positions(w, ww); ww
    ['b', 'd']

If the same vein you can also add links to Wikipedia: :wikipedia:`Sage_(mathematics_software)` add the following link to the Wikipedia article Sage_(mathematics_software)

Note

Finally, you can check that all links are properly resolved by adding the argument --warn-links to the documentation build command as in:

sage -docbuild --warn-links reference html

In this case, when a link is not resolved Sphinx will issue a warning.

Adding a new file

If you write a new file, say, sage/combinat/family.py, and you want your documentation to be added to the standard documentation, you have to add your file to the relevant index.rst file usually located in the tree:

SAGE_ROOT/devel/sage/doc/en/reference

For this example, you would need to add to the file

SAGE_ROOT/devel/sage/doc/en/reference/combinat/index.rst

the following line

 Combinatorics
 ============

 .. toctree::
    :maxdepth: 2

    ../sage/combinat/combinat
        [...]
    ../sage/combinat/dyck_word
+   ../sage/combinat/family
    ../sage/combinat/finite_class
        [...]

Building the manuals

All of the Sage manuals are built using the sage --docbuild script. The content of the sage --docbuild script is defined in SAGE_ROOT/devel/sage/doc/common/builder.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>

as explained below.

For more information, there are two help commands which give plenty of documentation for the sage --docbuild script:

sage --docbuild --help

(or -h) gives a basic listing of options and further help commands, while:

sage --docbuild --help-all

(or -H) shows a somewhat more comprehensive help message.

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

Output formats

The Sage documentation build system currently supports all of the output formats that Sphinx does.

For more detailed information, see the documentation on builders at http://sphinx.pocoo.org/builders.html .

Syntax highlighting Cython code

If you need to put Cython code in a ReST file, you can either precede the code block by .. code-block:: cython instead of the usual :: if you want to highlight one block of code in Cython, or you can use .. highlight:: cython for a whole file.

The following example was generated by .. code-block:: cython:

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)