.. highlight:: bash
.. _chapter-sage_manuals:
================
The Sage Manuals
================
Sage's manuals are written in `ReST <http://docutils.sourceforge.net/rst.html>`_
(reStructuredText), and generated with the software `Sphinx
<http://sphinx.pocoo.org>`_:
.. LIST-TABLE::
:widths: 4 12
:header-rows: 1
* - Name
- Files
* - `Tutorial <../tutorial/index.html>`_
- ``SAGE_ROOT/src/doc/en/tutorial``
* - `Developer's guide <../developer/index.html>`_
- ``SAGE_ROOT/src/doc/en/developer``
* - `Constructions <../constructions/index.html>`_
- ``SAGE_ROOT/src/doc/en/constructions``
* - `Installation guide <../installation/index.html>`_
- ``SAGE_ROOT/src/doc/en/installation``
* - `Reference manual <../reference/index.html>`_
- ``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 :ref:`section-manuals-names`.
.. _section-manuals-edit:
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 ``SAGE_ROOT/local/share/doc/sage/html/en/tutorial/index.html`` in
your web browser.
- Do you want to **add a new file** to the documentation? :ref:`Click here
<section-add-file>`.
- For more detailed information on the ``--docbuild`` command, see
:ref:`section-building-manuals`.
**Run doctests:** All files must pass tests. After modifying a document
(e.g. ``tutorial``), you can run tests with the following command (see
:ref:`chapter-testing`)::
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
.. _chapter-sage_manuals_links:
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 function, replace **:mod:** by
**:class:**, **:meth:** or **func:** respectively. See `Sphinx' documentation
<http://sphinx.pocoo.org/markup/inline.html>`_.
**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:
.. CODE-BLOCK:: rest
:func:`A link toward the integral function <integral>`
**Sage-specific roles:** Sage defines several specific *roles*:
.. LIST-TABLE::
:widths: 4 4 4
:header-rows: 0
* - Trac server
- ``:trac:`17596```
- :trac:`17596`
* - Wikipedia
- ``:wikipedia:`Sage_(mathematics_software)```
- :wikipedia:`Sage_(mathematics_software)`
* - arXiv
- ``:arxiv:`1202.1506```
- :arxiv:`1202.1506`
* - On-Line Encyclopedia of Integer Sequences
- ``:oeis:`A000081```
- :oeis:`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>`_``
**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
<https://stackoverflow.com/questions/27420317/>`__ 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
:ref:`section-building-manuals`.
.. _section-add-file:
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__.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``.
.. _section-building-manuals:
Building the Manuals
====================
*(Do you want to edit the documentation?* :ref:`Click here
<section-manuals-edit>`)
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/sage_docbuild/__init__.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
.. _section-manuals-names:
Document Names
--------------
The ``<document-name>`` has the form:
.. CODE-BLOCK:: text
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
Syntax Highlighting Cython Code
===============================
If you want to write :ref:`Cython <chapter-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:
.. CODE-BLOCK:: cython
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)