Some tips and tricks about the documentation system

I had some trouble to use the new documentation system. I'm putting here some tips and tricks. This page was build by gathering informations from the mailing list and irc. This may not be the right way to do. Please expand and correct...

1. How to write and compile Sage documentation


1.1. For the impatient


1.2. The ReST Format

The link quickref gives a not so short description of the format


1.3. Step by step instruction for building the doc

sage -b

to make sure that the sage is up-to-date with your modifications. Then depending of the desired format you call

sage -docbuild reference <format>

For example, I use the html format so that I call

sage -b && sage -docbuild reference html

Then the compiled doc is found at

$SAGE_ROOT/devel/sage/doc/output/html/en/reference/index.html

You can use you browser to view it...

sage -docbuild -help

explains all the sage -docbuild options.


The full explanation can be found at http://sphinx.pocoo.org/markup/inline.html

It is not possible to define chapters and labels and things in the autogenerated documentation ("because of the way it is produced" according to Mike Hansen), but as you will see there should be no needs. Indeed, it is possible to generate a link to the documentation for any module, class, method, function, etc. The syntax is

:role:`title <target>`

or

:role:`target`

where

If you don't provide any title then target will be used.

For example, to link the dyck_word module, you'd do something like :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 to 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. You dont need to give the full address of it. For example:

:meth:`to_dyck_word`

set up a link of the .to_dyck_word() method of the current class if it exists. If not the doc builder search further until it find a object or reach the toplevel module without finding it. If it occur the title is typeset in boldface without any link produced and also without any error or warning.


1.5. Adding a new file to the doc

If you write a new file say sage/combinat/family.py and you want your doc to be added to the system you have to add your file in the relevant index.rst file usually located in the tree:

$SAGE_ROOT/devel/sage-combinat/doc/en/reference

Going back to my example I have to add to the file

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


1.6. How to find the unincluded docs ?

They are currently a lot of file that hasn't been referenced. They do not appear in the doc. You can generate the list of those files by

sage -docbuild reference print_unincluded_modules


2. Trouble shooting

2.1. Compilation fails with "Too many open files"

File "/home/combi/hivert/Sage/sage-3.4/local/lib/python2.5/subprocess.py", line 1003, in _execute_child
    errpipe_read, errpipe_write = os.pipe()
OSError: [Errno 24] Too many open files
The full traceback has been saved in /tmp/sphinx-err--kaK6F.log, if you want to report the issue to the author.
Please also report this if it was a user error, so that a better error message can be provided next time.
Send reports to [email protected]. Thanks!
Build finished.  The built documents can be found in /home/combi/hivert/Sage/sage/devel/sage/doc/output/html/en/reference

I don't understand why but I nevertheless managed to build the doc using jsmath

sage -docbuild --jsmath all html


2.2. If you have deleted some doc file

Suppose that you added your file to some index.rst and then you delete it (e.g. by unapplying some patch). This cause some trouble because the build system left some garbage. Here there after unapplying the patch the file enumerated_sets.py does not exists anymore:

OSError: [Errno 2] No such file or directory: '/usr/local/sage/sage-3.4/devel/sage-combinat/doc/en/reference/sage/categories/enumerated_sets.rst'

Right now I don't know a good fix. Here are the methods I use:

If this still not work you can simply


3. Do you want to know more ?