.. _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/devel/sage/doc/en/tutorial``

-  The Sage developer's guide:
   ``SAGE_ROOT/devel/sage/doc/en/developer``

-  Constructions in Sage:
   ``SAGE_ROOT/devel/sage/doc/en/constructions``

-  The Sage installation guide:
   ``SAGE_ROOT/devel/sage/doc/en/installation``

-  The Sage reference manual: some of this is contained in the file
   ``SAGE_ROOT/devel/sage/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/devel/sage/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/devel/sage/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/devel/sage/doc/en/tutorial/``. Then to build a PDF file
with your changes, type::

    sage -docbuild tutorial pdf  

You'll get a file ``tutorial.pdf`` in
``SAGE_ROOT/devel/sage/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've 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/devel/sage/doc/output/html/en/tutorial/index.html`` in
your web browser.  For more detailed information about building the
documentation, see :ref:`building`.

You should also run

::
   
    sage -tp 1 SAGE_ROOT/devel/sage/doc/en/tutorial/

to test all of the examples in the tutorial - see
:ref:`chapter-testing`.

Finally, you might want to share your changes with the Sage
community. To do this, use Mercurial (see :ref:`chapter-mercurial`) to
produce patch files, and submit them to the Sage trac server.

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


Setting Hyperlink to Modules, Classes, Methods, etc
---------------------------------------------------

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...) 
  which carries the documentation to be linked to;

- ``title`` is the name of the link as shown in the browser.

If you don't 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 auto-generated. 

Finally local name 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 don't 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.

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/devel/sage/doc/en/reference

For this example, you would need to add to the file 

::

    $SAGE_ROOT/devel/sage/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
           [...]


.. _building:

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/devel/sage/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.  Use the following command to obtain
more documentation for the ``sage -docbuild`` script::

    sage -docbuild -help

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 isn't 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 .
