Hi there,
Rereading a few patch, I've found a bunch of systematically wrong Sphinx
markup. Just to make sure, let me recall a few fact about ReST and Sphinx.
First of all, when I'm unsure of a markup, I found [1] quite helpful as well
as concise. When a more advanced markup is needed I often use [2] and [3].
Now here is a random and non exhaustive lists of common mistakes:
1 - Do NOT indent bullet lists (unless you want extra indentation) and leave a
blank line at the end as
"""
INPUT:
- ``self`` -- bla bla
- ``opts`` -- ...
More text
"""
and not
"""
INPUT:
- ``self`` -- bla bla
- ``opts`` -- ...
More text
"""
2 - with multi-line explicit markup (note, warning, rubric, seealso...), the
following alignment must be respected
"""
.. seealso:: :class:`FinitePosets`, :class:`Lattices`,
:class:func:`LatticePoset`
"""
and not
"""
.. seealso:: :class:`FinitePosets`, :class:`Lattices`,
:class:func:`LatticePoset`
"""
3 - When using LaTeX markup (`...`) make sure to prefix the docstring with a r
to prevent control character expansion:
r"""
\right is not interpreted as \r + right
"""
Actually, I think that we should systematically prefix docstring with r.
4 - equation need not extra quote as in
r"""
.. math:: x\leq y \Rightarrow f(x) \leq f(y)
"""
and not
r"""
.. math:: `x\leq y \Rightarrow f(x) \leq f(y)`
"""
I hope this helps,
Florent
[1] http://docutils.sourceforge.net/docs/user/rst/quickref.html
[2] http://sphinx.pocoo.org/markup/index.html
[3] http://docutils.sourceforge.net/rst.html
--
To post to this group, send an email to sage-devel@googlegroups.com
To unsubscribe from this group, send an email to
sage-devel+unsubscr...@googlegroups.com
For more options, visit this group at http://groups.google.com/group/sage-devel
URL: http://www.sagemath.org
