The Sage Manuals¶
Sage’s manuals are written in ReST (reStructuredText), and generated with the software Sphinx:
Name |
Files |
|---|---|
SAGE_ROOT/src/doc/en/reference (most of it is generated from the source code) |
Additionally, more specialized manuals can be found under SAGE_ROOT/src/doc/en.
Some documents have been translated into other languages. In order to access them, change
en/intofr/,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 an HTML version of this document, type
$ meson compile -C builddir doc-html-other-en-tutorial
Here and below, replace builddir with the Meson build directory. An
editable pip installation uses build/cpXY, where X and Y are the
major and minor Python versions; for example, Python 3.12 uses build/cp312.
A build using Sage’s top-level Makefile uses build/sage-distro. See
Background information for details. You can now open
builddir/src/doc/html/en/tutorial/index.html in your web browser.
Do you want to add a new file to the documentation? Click here.
For more detailed information on the documentation build targets, see Building the manuals.
Run doctests: All files must pass tests. After modifying a document
(e.g. 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
$ meson compile -C builddir
$ meson compile -C builddir doc-html-reference-reference_top
Hyperlinks¶
The documentation can contain links toward modules, classes, or methods, e.g.:
:mod:`link to a module <sage.module_name>`
:mod:`sage.module_name` (here the link's text is the module's name)
For links toward classes, methods, or functions, replace :mod: by
:class:, :meth:, or :func:, respectively. See Sphinx’ documentation
on cross-referencing Python objects
and for the general syntax of
roles.
Short links: the link :func:`~sage.mod1.mod2.mod3.func1` is equivalent
to :func:`func1 <sage.mod1.mod2.mod3.func1>`: the function’s name will be
used as the link name, instead of its full path.
Local names: links between methods of the same class do not need to be
absolute. If you are documenting method_one, you can write
:meth:`method_two`.
Intersphinx references: in the same way, you can refer to the modules, classes, methods, functions of the Python standard library and of several Python packages used by SageMath; see the Intersphinx documentation for details. Likewise, you can refer to the C functions of the FLINT library; see Sphinx’ documentation on cross-referencing C constructs for more information.
Python |
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
To see the available cross references in any of these libraries, you can use the command
./sage -python -m sphinx.ext.intersphinx src/doc/common/_vendor/numpy.inv.
Global namespace: if an object (e.g. integral) is automatically imported
by Sage, you can link toward it without specifying its full path:
:func:`A link toward the integral function <integral>`
Sage-specific roles: Sage defines several specific roles:
GitHub issue |
|
|
Sage repository file or directory |
|
|
Wikipedia |
|
|
arXiv |
|
|
On-Line Encyclopedia of Integer Sequences |
|
|
Digital Object Identifier |
|
|
MathSciNet |
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
http links: copy/pasting a http link in the documentation works. If you want
a specific link name, use `link name <http://www.example.com>`_
Anonymous hyperlinks: Using a single underscore creates an explicit target
name "link name" which needs to be unique in the current page. Using the
same target name twice in the same page creates an error while building the
documentation saying WARNING: Duplicate explicit target name: .... To
avoid this issue, one can change the target names to be all different or
another option is to use anonymous hyperlinks with two underscores, as in
see `this page <http://www.example.com>`__ or `this page
<http://www.example2.com>`__.
Broken links: Sphinx can report broken links. See Building the manuals.
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
the file SAGE_ROOT/src/doc/en/reference/matroids/index.rst. Replace
‘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 SAGE_ROOT/src/doc/en/reference/combinat/module_list.rst.
Building the manuals¶
(Do you want to edit the documentation? Click here)
All Sage manuals are built through Meson targets. These targets invoke the
documentation builder in SAGE_ROOT/src/sage_docbuild, which is a wrapper
around Sphinx. The pip-installed sage command does not provide the legacy
--docbuild option, so use the Meson targets instead.
In the commands below, replace builddir with the Meson build directory.
For an editable pip installation this is build/cpXY, such as
build/cp312 for Python 3.12. A build using Sage’s top-level Makefile uses
build/sage-distro; see Background information. To build all
HTML or PDF manuals, use
$ meson compile -C builddir doc-html
$ meson compile -C builddir doc-pdf
Building PDF manuals requires a working LaTeX installation. The generated
manuals are written below builddir/src/doc/html and
builddir/src/doc/pdf, respectively.
Meson also provides targets for individual manuals. To list all configured targets, use
$ meson introspect builddir --targets
Broken links: in order to build the documentation while reporting the broken
links that it contains, pass --warn-links through
SAGE_DOCBUILD_OPTS. Note that Sphinx will not rebuild a document that has
not been updated, and thus not report its broken links.
$ SAGE_DOCBUILD_OPTS="--warn-links" meson compile -C builddir doc-html
Document names¶
Documentation sources outside the reference manual have the form
lang/name
where lang is a two-letter language code, and name is the
descriptive name of the document. The corresponding HTML target is named
doc-html-other-lang-name. For example, to build the English or French
tutorial, use
$ meson compile -C builddir doc-html-other-en-tutorial
$ meson compile -C builddir doc-html-other-fr-tutorial
Reference manual targets omit the language and other components. For
example, to build the combinatorics part of the reference manual, use
$ meson compile -C builddir doc-html-reference-combinat
Replace html with pdf in these target names to build PDF output.
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 ::. Enable
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)