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:
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
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).
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:
For this example, you would need to add to the file
the following line
Combinatorics ============ .. toctree:: :maxdepth: 2 ../sage/combinat/combinat [...] ../sage/combinat/dyck_word + ../sage/combinat/family ../sage/combinat/finite_class [...]
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.
The <document-name> has the form
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
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)