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/src/doc/en/tutorial
  • The Sage developer’s guide: SAGE_ROOT/src/doc/en/developer
  • Constructions in Sage: SAGE_ROOT/src/doc/en/constructions
  • The Sage installation guide: SAGE_ROOT/src/doc/en/installation
  • The Sage reference manual: some of this is contained in the file SAGE_ROOT/src/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/src/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/src/doc/fr/tutorial

Building the Manuals

If, for example, you want to change the Sage tutorial, then you should start by modifying the files in SAGE_ROOT/src/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/src/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/src/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 SAGE_ROOT/src/doc/en/tutorial/

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

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).

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/src/doc/en/reference

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

SAGE_ROOT/src/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
        [...]

Creating a Tutorial from a Worksheet

Sage has a number of thematic tutorials, especially those developed by the sage-combinat group. Sage has everything needed to take a worksheet created in the Sage notebook (sagenb) and then create a tutorial.

  • Once you have created a worksheet and are satisfied with the text and computations, download it to a directory.

We will assume here that the worksheet is called Tutorial.sws and the directory is called make_tutorial. We also assume that sage is your Sage command; if it is not in your PATH then replace this with the path to your Sage installation, such as /Applications/Sage-6.2.app/Contents/Resources/sage/sage if you are using the Mac app and have placed it in your Applications directory.

  • Next, you will need an optional package to parse your worksheet. Use the command:

    sage -i beautifulsoup
    

    to install it (or, in the Mac app, use the Terminal Session advanced menu with -i beautifulsoup).

  • Then we will use the sws2rst script to turn the worksheet into a document in the ReStructuredText format. Be sure you are in the same directory as the worksheet:

    sage --sws2rst Tutorial.sws
    

    This will create an .rst file along with a subdirectory of image files (which may be empty if there are no images).

    You can find help for sws2rst with the command sage --sws2rst -h once you have installed beautifulsoup.

  • In principle, such a file could be added directly to the documentation; see Adding a New File. If you add it to one of the manuals or the list of thematic tutorials, be sure to edit the toctree file as well, and put the line .. _tutorial-name: at the start of your file with the same listing as in the index.rst file.

    However, you probably want to check whether it looks right first. So next we will compile this file to html documentation.

    • Follow the instructions of sage --sws2rst --sphinxify. First, we will open a Sage shell session, where all appropriate Sage references already work properly:

      sage --sh
      

      From here, you should be able to just type:

      sphinx-quickstart
      

      and then respond to prompts for turning your .rst file into documentation. For most of them you can just hit enter/return to accept the defaults. However, you will probably want to

      • Enter a name for the project
      • Enter a name for you
      • Type y for the question about using MathJax

      Keep note of the instructions; the main other thing to do is add your file’s name to index.rst, and then just do:

      make html
      

      and wait while magic happens. To see the results, open the file make_tutorial/_build/html/Tutorial.html with a browser, or use your graphical file system to navigate to the same place.

  • Now you can modify the .rst file more and repeat the steps of compiling it until it is ready for inclusion, or just for distribution among other Sage users as an HTML file. (Do make pdf for a PDF version.)

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/src/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)