|
Size: 8943
Comment:
|
← Revision 26 as of 2022-04-07 01:08:53 ⇥
Size: 0
Comment: all of this is covered by https://doc.sagemath.org/html/en/developer/sage_manuals.html
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #pragma section-numbers 2 = 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 community and should not stay hidden inside combinat. I would be happy to move it elsewhere, if someone suggest me a proper place and from where to link it. If you move it, please don't forget to update the link at the bottom of the [[combinat|sage-combinat]] home page -- Florent. <<TableOfContents(3)>> == How to write and compile Sage documentation == The format is called ReST for [[http://docutils.sourceforge.net/rst.html|ReStructuredText]] and the doc builder is called [[http://sphinx.pocoo.org/|Sphinx]] ---- === 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}}}) ---- === The ReST 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 === * 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. ---- === Setting hyperlink to modules, classes, methods, etc === 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 * {{{role}}} is the kind of thing you what to link to (ie {{{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 carry the doc to be linked to; * {{{title}}} is the name the link appear in the browser. 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 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 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 going up in the class/module hierarchy of python until it find a object under this name 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. Note that without the prepended dot the object is searched starting from the toplevel to the innermost module/class. * I don't know is it's possible and how to activate some report of the missing targets -- Florent ---- === 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 [...] }}} ---- === 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 }}} -------- == Trouble shooting == === 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 }}} ---- === 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 ! -------- == Do you want to know more ? == * Why was it decided to [[http://wiki.sagemath.org/SphinxSEP|switch]] ? * The new format of doc is called {{{reStructuredText}}} it is hosted on sourceforge at [[http://docutils.sourceforge.net/rst.html|ReST]]. -------- == Random tips and Tricks == === How to use "sage -t" outside sage tree === It does work, on has to use .py files. First do a {{{ export SAGE_PATH=<path_to_your_files> }}} then for each function, import your functions from the appropriate module/file, e.g., {{{ from my_module import my_func }}} Here is what worked for me (John Cremona). Suppose that I have a stand-alone .py file, say myfile.py, containing various functions with doctests. * No need to set any environment variables * Put the line {{{ from sage.all import * }}} at the top of the file. * cd to the directory the file is in and type {{{ sage -t myfile.py }}} === Emacs mode for editing ReST files === It seems to be included in every major Linux distributions. For Ubuntu 8.10 things worked out of the box with {{{python-docutils.rpm}}} installed. For SuSE 11.1, the file is in {{{docutils.rpm}}} but not in emacs search path so you have to link it from {{{ /usr/share/doc/packages/docutils/tools/editors/emacs/rst.el }}} to whatever place in emacs load path. To load it you have also to load {{{lazy-lock}}} before because is not automatically loaded since it is marked as obsolete: {{{ (require 'lazy-lock) (require 'rst) }}} You can find informations on [[http://docutils.sourceforge.net/docs/user/emacs.html]] -------- '''~+Have a nice doc !!!+~''' |
