|
Size: 2675
Comment:
|
Size: 4279
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| I had some trouble to use the new documentation system. I'm putting here some tips and tricks. For now on, it's only my "experience returns" so that this may not be the right way to do. Please expand and correct... | 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... |
| Line 5: | Line 5: |
| == For the impatient == | ---- === For the impatient === |
| Line 7: | Line 8: |
| The two most important things to know are * {{{``inline literal``}}} for sage raw code |
The two most important things to know are * {{{``inline literal``}}} for sage raw code |
| Line 10: | Line 11: |
| * {{{`LaTeX interpreted text`}}} for mathematics | * {{{`LaTeX interpreted text`}}} for mathematics |
| Line 12: | Line 13: |
| * Any line ending with {{{::}}} means that the following indented things are a literal block (usually {{{sage: commands}}}) == Quick ref of the format == |
* Any line ending with {{{::}}} means that the following indented things are a literal block (usually {{{sage: commands}}}) |
| Line 16: | Line 15: |
| The link [[http://docutils.sourceforge.net/docs/user/rst/quickref.html|quickref]] gives a not so short description of the format. | ---- === The ReST Format === |
| Line 18: | Line 18: |
| == Step by step instruction for building the doc == | The link [[http://docutils.sourceforge.net/docs/user/rst/quickref.html|quickref]] gives a not so short description of the format |
| Line 20: | Line 20: |
| * Here are the step if you want to rebuild the doc at home: First issue a | ---- === Step by step instruction for building the doc === * First issue a |
| Line 38: | Line 41: |
| == Getting help on the docbuild system == | |
| Line 40: | Line 42: |
| * You can get some help on the docbuild system by: | |
| Line 45: | Line 48: |
| == How to find the unincluded docs ? == | ---- === 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 [...] }}} ---- === How to find the unincluded docs ? === |
| Line 52: | Line 83: |
| ---- ---- |
|
| Line 57: | Line 91: |
---- ---- |
|
| Line 76: | Line 113: |
| ---- === 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 ! |
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...
0.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)
0.2. The ReST Format
The link quickref gives a not so short description of the format
0.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.
0.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
[...]
0.5. How to find the unincluded docs ?
You can generate such the list by:
sage -docbuild reference print_unincluded_modules
1. 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.
2. Trouble shooting
- 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
2.1. 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 !!!