Wiki
Clone wikisage_coding_project / Howto_Documentation
Here are some tips for the documentation in Sage:
- Build the documentation : sage --docbuild reference/your_folder Do not forget to build (sage -b) your changes before.
- Add a new file to the reference manual : change SAGE_ROOT/src/doc/en/reference/your_folder/index.rst
- Headings of files : http://www.sagemath.org/doc/developer/coding_basics.html#headings-of-sage-library-code-files
- Be careful with the encoding! All files must be us-ascii. Useful check-up command :
file --mime <filename>
-
Be careful with blank lines too. Every text block that ends with two columns should be followed by a blank line, else you'll end up with a strange, unspecific indentation error :
#This is good: r""" EXAMPLES:: sage: stuff And here is more stuff:: sage: more stuff """ #This is wrong: r""" EXAMPLES:: sage: stuff And here is more stuff:: sage: more stuff """
-
If you ever get an unhelpful error message of the form
<path>/sage/coding/linear_code.py:docstring of sage.coding.linear_code:21: ERROR: Unexpected indentation.
This is probably due to missing a blank line as above. The "21" is not a line number but probably refers to the 21st method of the file or class, counted in alphabetical order.
-
Use
r""" """
and not""" """
. Align text lines under the first backquote in INPUT block in case of multiple-line splitting.#This is good: r""" INPUT: - ``arg`` -- my first line is splitted right here and continues on second line """ #This is wrong: r""" INPUT: - ``arg`` -- my first line is splitted right here and continues on second line """
-
The first two lines of every file have to be :
r""" <title for the html page>
Some useful commands:
-
sage -t <filename> : runs doctests for selected file
-
sage --coverage <filename> : checks if selected file's methods are fully covered (docstrings + tests)
Updated