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

• It has been said on the mailing list that this page is of general interest for the sage comunity and should not stay hidden inside combinat. I (FlorentHivert) would be happy to move it elsewhere, if someone suggest me a proper place. If you move it, please don't forget to update the link at the bottom of the sage-combinat home page.

1. How to write and compile Sage documentation

---

1.1. For the impatient

• The two most important things to know are

  • ``inline literal`` for sage raw code

  • `LaTeX interpreted text` for mathematics

  • Any line ending with :: means that the following indented things are a literal block (usually sage: commands)

---

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

• First issue a

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

• You can get some help on the docbuild system by:

sage -docbuild -help

explains all the sage -docbuild options.

---

1.4. 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

$SAGE_ROOT/devel/sage-combinat/doc/en/reference/combinat/index.rst

The following lines

 Combinatorics
 =============

 .. toctree::
    :maxdepth: 2

    ../sage/combinat/combinat
           [...]
    ../sage/combinat/dyck_word
+   ../sage/combinat/family
    ../sage/combinat/finite_class
           [...]

---

1.5. Setting hyperlink between different help pages

TODO: Test and improve the following... See: http://sphinx.pocoo.org/markup/inline.html

Here is a short log of a discussion with Mike on IRC:

< mhansen> I don't have a whole lot of time (which is why I'm not responding
    to the email), but here's what you need to do for hyperlinking.  You can't
    define chapters and labels and things in the autogenerated documentation
    (because of the way it is produced).
< mhansen> If you want to generate a link to the documentation for the
    dyck_word module, you'd do something like :mod:`sage.combinat.dyck_word`
    and that will be turned into a link to the right place.
< mhansen> You can also do things like :class:``, :meth:``, etc.
< mhansen> The docs for cross-referencing are at
                 http://sphinx.pocoo.org/markup/inline.html
< hivert> The reference :class:`` and so one probably remove the needs to create new targets.

---

1.6. How to find the unincluded docs ?

You can generate such the list by:

sage -docbuild reference print_unincluded_modules

---

2. Do you want to know more ?

• Why was it decided to switch ?

• The new format of doc is called reStructuredText it is hosted on sourceforge at ReST.

---

3. Trouble shooting

3.1. Compilation fails with "Too many open files"

• On a machine I got the following error:

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

---

3.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:

• Delete all the copy of enumerated_sets.py and enumerated_sets.pyc at the various positions of $SAGE_ROOT/devel/sage/build

• Delete the enumerated_sets.rst file

If this still not work you can simply

• Nuke the whole $SAGE_ROOT/devel/sage/doc/output tree !

---

• Have a nice doc !!!