Add some info about sphinx and rest (including links) to developer guide

[jpflori]

There is a problem within ​http://www.sagemath.org/doc/developer/conventions.html. It says to use ".. NOTE::" and there is "NOTES:" in the example.

There is also nothing about "TESTS:" section which is often used whithin the source code.

The recurrent use of ".. blah ::", "::" and "sage: " could also be documented or at least directly point to the corresponding pages of Sphynx doc (even if looking at the examples is of course the best way to go and looking through Sphynx doc also explains many things).

[mvngu]

There is a problem within ​http://www.sagemath.org/doc/developer/conventions.html. It says to use ".. NOTE::" and there is "NOTES:" in the example.

Fixed in the attached patch.

There is also nothing about "TESTS:" section which is often used whithin the source code.

Fixed in the attached patch.

The recurrent use of ".. blah ::", "::" and "sage: " could also be documented

Fixed in the attached patch.

or at least directly point to the corresponding pages of Sphynx doc

Fixed in the attached patch.

[novoselt]

I a bit disagree with the interpretation of "TESTS" directive. I tend to put there any tests that do not really help in illustrating the function. For example, if there was a bug detected on some valid but long and perhaps obscure input, I think that it should go to TESTS. On the other hand, if some exceptions are not unusual, they may very well be illustrated in EXAMPLES, e.g. solving an overdetermined system of equations. Personally, I think that EXAMPLES are bits of code that show how to use a function. Bits of code that make sure that every branch of code got executed can be much more numerous than necessary for illustration.

What's the point of "notes" in lower case? Is it really necessary for something or maybe it is possible to list only .. NOTES::?

[jpflori]

Thanks a lot for the patch. I guess with it the situation for newcomers as myself will be much clearer.

I kind of agree with novoselt statement about what EXAMPLES and TESTS blocks should be used for, but don't know what was decided by Sage devs because of the lack of doc before what you just produced.

About the "notes" and "warning" in lower case, they could maybe be mentionned but their use strongly discouraged (e.g. "you'll also find a lot of ".. notes::" in existing source code, which is valid, but the use of the lower case version is strongly discouraged", or "we are currently in the process of converting everything to uppercase").

[mhansen]

Why are we saying that the uppercase version of the directives should be used? I can't think of any other Sphinx based documentation project that does that.

[mvngu]

Replying to novoselt:

I a bit disagree with the interpretation of "TESTS" directive. I tend to put there any tests that do not really help in illustrating the function. For example, if there was a bug detected on some valid but long and perhaps obscure input, I think that it should go to TESTS.

And also providing the corresponding ticket number (if available) of the ticket for that bug.

On the other hand, if some exceptions are not unusual, they may very well be illustrated in EXAMPLES, e.g. solving an overdetermined system of equations.

This depends on the specific case. But I agree with this comment of yours.

Personally, I think that EXAMPLES are bits of code that show how to use a function.

Nod.

Bits of code that make sure that every branch of code got executed can be much more numerous than necessary for illustration.

Nod. Such code can go in the TESTS block. If there are too many such tests, create a sepatate test file, but don't include them in the reference manual.

What's the point of "notes" in lower case? Is it really necessary for something or maybe it is possible to list only .. NOTES::?

I tend to encourage the use of the Sphinx directive for notes. That is, use the lower-case ".. note::" or the upper-case version ".. NOTE::" (choose one). But Sphinx doesn't recognize ".. notes::" nor ".. NOTES::" (notice the "s" before the double colon). Both the ​Sphinx and the ​ReST documentation say that "notes" with an "s" is not supported.

See my ​comment at #10078 for reasons why I encourage (but not say "must") the use of upper-case versions of admonitions, etc.

[mvngu]

Replying to mhansen:

Why are we saying that the uppercase version of the directives should be used? I can't think of any other Sphinx based documentation project that does that.

For consistency with "INPUT", "OUTPUT", "EXAMPLES" and "TESTS". See my ​comment at #10078. It's fine by me to say this: Sphinx supports both the lower- and upper-cases for "warning", "note", "math", etc.

[mariah]

patch trac-10077_clarify-conventions.patch​ fails to apply to sage-4.7.rc4. Perhaps needs to be rebased?

sage: hg_sage.apply("/home/mariah/trac-10077_clarify-conventions.patch")
cd "/home/mariah/sage/sage-4.7.rc4-x86_64-Linux-core2-fc-review-10077/devel/sage" && hg status
cd "/home/mariah/sage/sage-4.7.rc4-x86_64-Linux-core2-fc-review-10077/devel/sage" && hg status
cd "/home/mariah/sage/sage-4.7.rc4-x86_64-Linux-core2-fc-review-10077/devel/sage" && hg import   "/home/mariah/trac-10077_clarify-conventions.patch"
applying /home/mariah/trac-10077_clarify-conventions.patch
patching file doc/en/developer/conventions.rst
Hunk #2 FAILED at 109
1 out of 11 hunks FAILED -- saving rejects to file doc/en/developer/conventions.rst.rej
abort: patch failed to apply
sage:

[kcrisman]

I have checked, and most of this is much better in the current developer guide. However, I think that a little more info about Sphinx and ReST as in this patch would be good, though perhaps not right at the start of that part!

[jhpalmieri]

Nathann, since you've been looking at documentation recently, do you have any opinion about this?

[ncohen]

Nathann, since you've been looking at documentation recently, do you have any opinion about this?

Well, as Karl-Dieter said Minh's point about Notes/Tests has been solved already. As for explaining the syntax of :: and sage: I do not know the doc sufficiently well to know where it should be done. I am not too worried about that, given that as Minh said people will learn that through looking at sources (and all examples from the manual that use this syntax already).

Minh is always right anyway.

Nathann

P.S.: If you have some time for a couple of reviews, I have two very short tickets that only move stuff around: #17614 and #17615