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:
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
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 -help).
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
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.
Finally, 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.
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
[...]
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. Use the following command to obtain more documentation for the sage -docbuild script:
sage -docbuild -help
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
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 .