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¶
(Do you want to convert a Sage worksheet into documentation? Click here)
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 Tests):
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_setup/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)