Path: blob/master/src/doc/en/developer/sage_manuals.rst
8815 views
.. _chapter-sage_manuals:
================
The Sage Manuals
================
This chapter describes how to modify the Sage manuals. Sage's manuals
are written in ReST, otherwise known as `reStructuredText`__. To edit
them, you just need to edit the appropriate file. The documentation
builder is called `Sphinx`__.
__ http://docutils.sourceforge.net/rst.html
__ http://sphinx.pocoo.org
Here is a list of the Sage manuals and the corresponding files to edit:
- The Sage tutorial: ``SAGE_ROOT/src/doc/en/tutorial``
- The Sage developer's guide:
``SAGE_ROOT/src/doc/en/developer``
- Constructions in Sage:
``SAGE_ROOT/src/doc/en/constructions``
- The Sage installation guide:
``SAGE_ROOT/src/doc/en/installation``
- The Sage reference manual: some of this is contained in the file
``SAGE_ROOT/src/doc/en/reference``, but most of it is
automatically generated from the Sage source code.
- Additional, more specialized manuals can be found under
``SAGE_ROOT/src/doc/en`` as well.
.. note::
You can edit manuals that have been translated into another language
by replacing the ``en/`` above with the appropriate two letter
language code. For example, the French tutorial is located in
``SAGE_ROOT/src/doc/fr/tutorial``
Editing the Manuals
===================
If, for example, you want to change the Sage tutorial, then you should
start by modifying the files in
``SAGE_ROOT/src/doc/en/tutorial/``. Then to build a PDF file
with your changes, type::
sage --docbuild tutorial pdf
You will get a file ``tutorial.pdf`` in
``SAGE_ROOT/src/doc/output/pdf/en/tutorial`` which you should
inspect. You can build the HTML version of the tutorial by typing::
sage --docbuild tutorial html
Once you have done this, you can access the new HTML version from the
notebook interface to Sage by clicking the ``Help`` link, or you can
open the file
``SAGE_ROOT/src/doc/output/html/en/tutorial/index.html`` in
your web browser. For more detailed information about building the
documentation, see :ref:`section-building-manuals`.
You should also run::
sage -tp SAGE_ROOT/src/doc/en/tutorial/
to test all of the examples in the tutorial, see
:ref:`chapter-testing` for more details.
As noted above, the reference manual is mostly autogenerated from Sage
source code. To build it, type::
sage -b <repo-name>
sage --docbuild reference <format>
where ``<repo-name>`` is the name of the repository you are using, and
``<format>`` is ``html``, ``pdf``, or any other supported format (as listed
when you run ``sage --docbuild --formats``).
.. _chapter-sage_manuals_links:
Hyperlinks
==========
You can link to doctstings of modules, classes, methods. In addition,
you can link web pages like trac tickets and Wikipedia. For full
documentation, refer to `inline markup`__ in the Sphinx
documentation. Currently, there is no support for defining chapters
and labels in the autogenerated documentation. However, it is possible
to generate a link to the documentation for any module, class, method,
function, etc. The syntax is
__ http://sphinx.pocoo.org/markup/inline.html
::
:role:`title <target>`
or
::
:role:`target`
where
- ``role`` is the kind of thing you want to link to (i.e. ``mod`` for
module, ``class`` for classes, ``meth`` for methods, ``func`` for
functions, etc;
- ``target`` is the Python name of the object (class, module, method,
etc.) which carries the documentation to be linked to;
- ``title`` is the name of the link as shown in the browser.
If you do not provide any title then target will be used. For example,
to link to the ``dyck_word`` module, you would use
``:mod:`sage.combinat.dyck_word``` or if you prefer ``:mod:`Dyck
words<sage.combinat.dyck_word>```. Note that, in the first case, the
full qualified Python address is used which is usually too long. You
can prefix it with a ``"~"`` to get only the final name. For example,
in the huge link::
:meth:`~sage.combinat.non_decreasing_parking_function.NonDecreasingParkingFunction.to_dyck_word`
only ``".to_dyck_word()"`` will appear. Note that the parentheses in
the link are autogenerated.
Local names are handled. That is, for example, in the definition of a
class (and any of its members or methods), you can link to any member
or method of the same class by simply giving the name of it prepended
by a dot ``"."``. You do not need to give its full address. For
example::
:meth:`.to_dyck_word`
sets up a link to the ``.to_dyck_word()`` method of the current class
if it exists. If not, the documentation builder searches by going up
in the class/module hierarchy of Python until it finds an object with
this name or reaches the top-level module without finding it. If the
name cannot be found, the title is typeset in boldface without any
link produced and also without any error or warning. Note that without
the prepended dot, the object is searched starting from the top-level
to the innermost module or class.
You can also link, without giving the full path, to objects imported
in a local module or imported by default in Sage. For example, the two
following are equivalent, as :class:`Parent` is imported by default in
Sage (using the ``all.py`` files)::
:class:`Parent`
:class:`~sage.structure.parent.Parent`
Sage adds a special role to link to trac ticket. The code
``:trac:`12490``` link to the :trac:`12490`. When fixing a bug, you
should add the link to the corresponding trac ticket in the ``TEST``
section. Here is an example::
TEST:
We check for :trac:`5534`::
sage: w = ["a", "b", "c", "d"]; ww = ["b", "d"]
sage: x = sage.combinat.subword.smallest_positions(w, ww); ww
['b', 'd']
In the same vein, you can also add external links of various kinds:
- Wikipedia: ``:wikipedia:`Sage_(mathematics_software)``` adds the
link :wikipedia:`Sage_(mathematics_software)`.
- Arxiv: ``:arxiv:`1202.1506``` adds the link :arxiv:`1202.1506`.
- On-Line Encyclopedia of Integer Sequences: ``:oeis:`A000081``` adds
the link :oeis:`A000081`.
- Digital Object Identifier: ``:doi:`10.2752/175303708X390473``` adds
the link :doi:`10.2752/175303708X390473`.
- MathSciNet: ``:mathscinet:`MR0100971``` adds the link
:mathscinet:`MR0100971`.
.. note::
Finally, you can check that all links are properly resolved by
adding the argument ``--warn-links`` to the documentation build
command as in::
sage -docbuild --warn-links reference html
In this case, when a link is not resolved Sphinx will issue a
warning.
Adding a New File
=================
If you write a new file, say, ``sage/combinat/family.py``, and you
want your documentation to be added to the standard documentation, you
have to add your file to the relevant ``index.rst`` file usually
located in the tree::
SAGE_ROOT/src/doc/en/reference
For this example, you would need to add to the file::
SAGE_ROOT/src/doc/en/reference/combinat/index.rst
the following line::
Combinatorics
=============
.. toctree::
:maxdepth: 2
../sage/combinat/combinat
[...]
../sage/combinat/dyck_word
+ ../sage/combinat/family
../sage/combinat/finite_class
[...]
.. _section-building-manuals:
Building the Manuals
====================
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>
as explained below. For more information, there are two help commands
which give plenty of documentation for the ``sage --docbuild``
script::
sage --docbuild --help
(or ``-h``) gives a basic listing of options and further
help commands, while::
sage --docbuild --help-all
(or ``-H``) shows a somewhat more comprehensive help message.
Document Names
--------------
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
Output Formats
--------------
The Sage documentation build system currently supports all of the
output formats that Sphinx does. For more detailed information, see
the documentation on builders at http://sphinx.pocoo.org/builders.html
.
Syntax Highlighting Cython Code
===============================
If you need to put :ref:`Cython <chapter-cython>` code in a ReST file,
you can either precede the code block by ``.. code-block:: cython`` instead
of the usual ``::`` if you want to highlight one block of code in Cython,
or you can use ``.. highlight:: cython`` for a whole file.
The following example was generated by ``.. code-block:: cython``:
.. 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)