Documentation tips...
Florent Hivert
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
Simon King
On 23 Apr., 15:27, Florent Hivert <florent.hiv...@univ-rouen.fr>
wrote:
>
> 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.
contains any backslash.
There is another quite common mistake:
It should be
EXAMPLE::
sage: bla
and not
EXAMPLE:
sage: bla
Just to avoid duplication of work: We killed a bunch of those mistakes
in #9976.
Cheers,
Simon
Florent Hivert
> There is another quite common mistake:
>
> It should be
> EXAMPLE::
>
> sage: bla
>
> and not
>
> EXAMPLE:
> sage: bla
Sure ! I thought this one was too basic...
> Just to avoid duplication of work: We killed a bunch of those mistakes
> in #9976.
Thanks !!! To avoid endless problem with rebasing sage-combinat queue, It
could really help if this patch could be the first one of a release (say
4.7.1)...
Cheers,
Florent
Simon King
On 23 Apr., 15:56, Florent Hivert <florent.hiv...@univ-rouen.fr>
wrote:
Isn't there a skript to find common markup errors? If not, it would
seem useful to write one.
> Thanks !!! To avoid endless problem with rebasing sage-combinat queue, It
> could really help if this patch could be the first one of a release (say
> 4.7.1)...
for one of the patches.
Cheers,
Simon
kcrisman
On Apr 23, 9:56 am, Florent Hivert <florent.hiv...@univ-rouen.fr>
wrote:
>
> > There is another quite common mistake:
>
> > It should be
> > EXAMPLE::
>
> > sage: bla
>
> > and not
>
> > EXAMPLE:
> > sage: bla
>
EXAMPLES:
We here give an interesting example::
sage: bla
A lot of this could be avoided by people doing "./sage -docbuild
reference html" or whatever is relevant, but I have to admit that,
until you get used to doing that, it seems like a big pain.
If these tips are not in the devel guide, maybe they should be added
in a footnote or something.
Robert Bradshaw
>
>
> On Apr 23, 9:56 am, Florent Hivert <florent.hiv...@univ-rouen.fr>
> wrote:
>> Hi Simon,
>>
>> > There is another quite common mistake:
>>
>> > It should be
>> > EXAMPLE::
>>
>> > sage: bla
>>
>> > and not
>>
>> > EXAMPLE:
>> > sage: bla
>>
>
>
> And it should be
>
>
> EXAMPLES:
>
> We here give an interesting example::
>
> sage: bla
>
>
> A lot of this could be avoided by people doing "./sage -docbuild
> reference html" or whatever is relevant, but I have to admit that,
> until you get used to doing that, it seems like a big pain.
Even if you get used to doing it, it's a big pain due to the amount of
time it takes. As requested, it was added to the patchbot, and this
step alone takes more time than rebuilding the entire Sage library
plus running all the tests (i.e. in real time, the patchbot spends the
majority of its time running Sphinx). We really need to find a way to
speed this up, parallelizing it an otherwise.
- Robert
Keshav Kini
> We really need to find a way to
> speed this up, parallelizing it an otherwise.
-Keshav
Dr. David Kirkby
> 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.
Is there a way of forcing Sphinx to reject these, so we find them? A C compiler
should not allow one to compile code that has syntax errors, so why should Sphinx?
Dave
Simon King
On 24 Apr., 11:19, "Dr. David Kirkby" <david.kir...@onetel.net> wrote:
> Is there a way of forcing Sphinx to reject these, so we find them? A C compiler
> should not allow one to compile code that has syntax errors, so why should Sphinx?
it is not *always* raising the warnings. E.g., at #9976, some warnings
only came up after applying the original patch versions, although the
syntax error itself was present without the patches.
Moreover, the warning messages are often not helpful.
However, things like
"""
EXAMPLE:
sage: bla
"""
are no syntax error: They are valid, but they are not typeset in the
intended way. So, *refusing* it would not be the right answer, IMO.
But I think it would be easy to write a skript that searches for
certain typical patterns (like
"""
INPUT:
- <some text>
""")
and suggests to replace it by
"""
INPUT:
- <some text>
"""
That would be in the same spirit as the coverage skript, that does not
refuse things, but points to potential issues.
Best regards,
Simon
Nicolas M. Thiery
> And it should be
>
> EXAMPLES:
>
> We here give an interesting example::
>
> sage: bla
+1 on the S to EXAMPLES. And, when not obvious, +1 on having a
description of the intention of the example is doing.
On the other hand, there is no point in adding a sentence like "We
here give an interesting example", as it does not bring any
information: EXAMPLES by itself tells we are going to give an example;
and as a doc writer, one should strive at choosing interesting
examples anyway, but one can't decide for the reader whether (s)he
will actually find it interesting.
Cheers,
Nicolas
--
Nicolas M. Thi�ry "Isil" <nth...@users.sf.net>
http://Nicolas.Thiery.name/
kcrisman
On Apr 25, 8:04 am, "Nicolas M. Thiery" <Nicolas.Thi...@u-psud.fr>
wrote:
> > And it should be
>
> > EXAMPLES:
>
> > We here give an interesting example::
>
> > sage: bla
>
> +1 on the S to EXAMPLES. And, when not obvious, +1 on having a
> description of the intention of the example is doing.
>
> On the other hand, there is no point in adding a sentence like "We
> here give an interesting example", as it does not bring any
> information: EXAMPLES by itself tells we are going to give an example;
would not be 'bla', unless that has now been imported into the global
namespace :)
Keshav Kini
-Keshav
----
Join us in #sagemath on irc.freenode.net !
Niles
> On the other hand, there is no point in adding a sentence like "We
> here give an interesting example", as it does not bring any
> information:
out an interesting one.
But seriously, has anyone opened a ticket for the original suggestions
yet? They are very good, and it would be a shame to loose track of
them.
-Niles
Kwankyu Lee
The first one line of every method docstring should be written as a command. Hence
"""
Return true if blah blah
rather than
"""
Returns true if blah blah
Kwankyu
Maarten Derickx
On Apr 26, 2:17 am, Keshav Kini <keshav.k...@gmail.com> wrote:
> In general I think it might be useful to have a "sage-lint" script to find
> and highlight weird or probably weird stuff in the codebase. This could
> subsume both your suggested script and the coverage script, as well as
> perhaps look for python 2.x -> 3.x issues, internal usage of deprecated
> functions, etc.
>
> -Keshav
>
This is also one of the items on my personal "ideas to enhance sage"-
list. I think we should first try to make a working pylint spkq so we
can use it to write our sage specific pylint plugins.
Kind regards,
Maarten Derickx