Sage’s manuals are written in ReST (reStructuredText), and generated with the software Sphinx:

Name | Files |
---|---|

Tutorial | SAGE_ROOT/src/doc/en/tutorial |

Developer’s guide | SAGE_ROOT/src/doc/en/developer |

Constructions | SAGE_ROOT/src/doc/en/constructions |

Installation guide | SAGE_ROOT/src/doc/en/installation |

Reference manual | 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/ into fr/,es/, de/... See*Document Names*.

(*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 `SAGE_ROOT/src/doc/output/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
`--docbuild`command, 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 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
```

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 function, replace **:mod:** by
**:class:**, **:meth:** or **func:** respectively. See Sphinx’ documentation.

**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``.

**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*:

Trac server | :trac:`17596` |
trac ticket #17596 |

Wikipedia | :wikipedia:`Sage_(mathematics_software)` |
Wikipedia article Sage_(mathematics_software) |

Arxiv | :arxiv:`1202.1506` |
Arxiv 1202.1506 |

On-Line Encyclopedia of Integer Sequences | :oeis:`A000081` |
OEIS sequence A000081 |

Digital Object Identifier | :doi:`10.2752/175303708X390473` |
doi:10.2752/175303708X390473 |

MathSciNet | :mathscinet:`MR0100971` |
MathSciNet MR0100971 |

**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>`_`

**Broken links:** Sphinx can report broken links. See
*Building the Manuals*.

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__.py`file 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`.

*(Do you want to edit the documentation?* *Click here*)

All of the Sage manuals are built using the `sage --docbuild`
script. The content of the `sage --docbuild` script is defined in
`SAGE_ROOT/src/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>
```

For example:

```
sage --docbuild reference html
```

Two **help** commands which give plenty of documentation for the `sage
--docbuild` script:

```
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
links:

```
sage --docbuild --warn-links reference html
```

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
```

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)
```