Differences between revisions 1 and 5 (spanning 4 versions)
⇤ ← Revision 1 as of 2009-03-01 17:32:45 →
Size: 1183
Editor: FlorentHivert
Comment: Added Tips & Tricks about the doc.
← Revision 5 as of 2009-03-18 14:02:20 → ⇥
Size: 2670
Editor: FlorentHivert
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
I've add 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. For now on, it's only my "experience returns" so that this may not be the right way to do. Please expand and correct...

== For the impatient ==

The two most important things to know are
 * {{{``inline literal``}}} for sage row code
 
 * {{{`LaTeX interpreted text`}}} for mathematics

 * Any line ending with {{{::}}} means that the following indented things are a literal block (usually {{{sage: commands}}})
 
== Quick ref of the format ==

The link [[http://docutils.sourceforge.net/docs/user/rst/quickref.html|quickref]] gives a not so short description of the format.

== Step by step instruction for building the doc ==

 * Here are the step if you want to rebuild the doc at home: 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...

== Getting help on the docbuild system ==

{{{
sage -docbuild -help
}}}
explains all the {{{sage -docbuild}}} options.

== How to find the unincluded docs ? ==

You can generate such the list by:
{{{
sage -docbuild reference print_unincluded_modules
}}}

== Do you want to know more ? ==
Line 9: Line 58:
 * For the impatient the following [[http://docutils.sourceforge.net/docs/user/rst/quickref.html|quickref]] gives a not so short description of the format. == Trouble shooting ==
Line 11: Line 60:
 * Here are the step if you want to rebuild the doc at home: 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...		 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
}}}

                Have a nice doc !!!

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. For now on, it's only my "experience returns" so that this may not be the right way to do. Please expand and correct...

For the impatient

The two most important things to know are

  • ``inline literal`` for sage row code

  • `LaTeX interpreted text` for mathematics

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

Quick ref of the format

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

Step by step instruction for building the doc

  • Here are the step if you want to rebuild the doc at home: 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...

Getting help on the docbuild system

sage -docbuild -help

explains all the sage -docbuild options.

How to find the unincluded docs ?

You can generate such the list by: 

sage -docbuild reference print_unincluded_modules

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.

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
  • Have a nice doc !!!