The Sage Manuals#
Additionally, more specialized manuals can be found under
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
your web browser.
Do you want to add a new file to the documentation? Click here.
For more detailed information on the
--docbuildcommand, see Building the Manuals.
Run doctests: All files must pass tests. After modifying a document
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
‘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__.pyfile located in the directory that contains your file.
Add your file to the index contained in
Building the Manuals#
(Do you want to edit the documentation? Click here)
All of the Sage manuals are built using the
script. The content of the
sage --docbuild script is defined in
SAGE_ROOT/src/sage_docbuild/__init__.py. It is a thin wrapper around
sphinx-build script which does all of the real work. It is
designed to be a replacement for the default Makefiles generated by
sphinx-quickstart script. The general form of the command
sage --docbuild <document-name> <format>
sage --docbuild reference html
Two help commands which give plenty of documentation for the
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://sphinx.pocoo.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
sage --docbuild --warn-links reference html
<document-name> has the form:
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
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)