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)