Testing rst files...
Florent Hivert
I'm currently preparing a few of demo for sage days 28. I'm using .rst file
for the demo. Indeed, compared to notebook it can be edited by hand, and it
allows easier distribution and versioning. However I'm having trouble with
sage -t. Suppose I'm writing the following .rst file
"""
Examples of code::
sage: el = 1
sage: el
1
Some explanations::
sage: el
1
"""
Then launching sage -t give the following error on the second example:
sage: el
NameError: name 'el' is not defined
It seems that it forget the variables at each new block of code. Is this
behavior normal ? Intended ? Or a bug ? Isn't a .rst file considered as a big
docstring by the tester ?
Cheers,
Florent
John H Palmieri
wrote:
>
> I'm currently preparing a few of demo for sage days 28. I'm using .rst file
> for the demo. Indeed, compared to notebook it can be edited by hand, and it
> allows easier distribution and versioning. However I'm having trouble with
> sage -t. Suppose I'm writing the following .rst file
>
> """
> Examples of code::
>
> sage: el = 1
> sage: el
> 1
>
> Some explanations::
>
> sage: el
> 1
> """
>
> Then launching sage -t give the following error on the second example:
>
> sage: el
> NameError: name 'el' is not defined
>
> It seems that it forget the variables at each new block of code. Is this
> behavior normal ? Intended ? Or a bug ?
> Isn't a .rst file considered as a big docstring by the tester ?
Before the second code block, you need a "link" directive to tell it
that it should be connected with the previous block. See
<http://sagemath.org/doc/developer/conventions.html#testing-rest-
documentation>
for documentation. For an example, see the file "interfaces.rst" in
the tutorial. Your example could look like this:
Examples of code::
sage: el = 1
sage: el
1
Some explanations:
::
sage: el
1
(Note the double colon after ".. link", so only a single colon after
"Some explanations".)
--
John
Florent Hivert
> > Isn't a .rst file considered as a big docstring by the tester ?
>
> No.
>
> Before the second code block, you need a "link" directive to tell it
> that it should be connected with the previous block. See
>
> <http://sagemath.org/doc/developer/conventions.html#testing-rest-
> documentation>
Thanks for the tip ! I completely missed it. Sorry for asking a "read the
F****** manual" question.
Cheers,
Florent
Florent Hivert
> Before the second code block, you need a "link" directive to tell it
> that it should be connected with the previous block. See
>
> <http://sagemath.org/doc/developer/conventions.html#testing-rest-
> documentation>
>
> for documentation. For an example, see the file "interfaces.rst" in
> the tutorial. Your example could look like this:
>
>
> Examples of code::
>
> sage: el = 1
> sage: el
> 1
>
> Some explanations:
>
> .. link
>
> ::
>
> sage: el
> 1
>
> (Note the double colon after ".. link", so only a single colon after
> "Some explanations".)
It seems that doesn't work inside a note environement:
"""
Title
=====
Some explanations::
sage: v = 1
Some more explanations:
.. link::
::
sage: v
1
.. note::
If you are in that particular case:
.. link::
::
sage: v
1
"""
popcorn-*/reference/demos $ sage -t bug.rst
sage -t "bug.rst"
**********************************************************************
File "/home/data/Sage-Install/sage-4.6/devel/sage-combinat/doc/en/reference/demos/bug.rst", line 25:
sage: v
Exception raised:
Traceback (most recent call last):
...
sage: v
NameError: name 'v' is not defined
**********************************************************************
Did I miss something else ?
Cheers,
Florent
Florent Hivert
> Examples of code::
>
> sage: el = 1
> sage: el
> 1
>
> Some explanations:
>
> .. link
>
> ::
>
> sage: el
> 1
>
> (Note the double colon after ".. link", so only a single colon after
> "Some explanations".)
In conventions.html#testing-rest-documentation you write
"""
environments, use the ``.. link::`` comment. For example::
::
sage: a = 1
Next we add 1 to ``a``.
.. link::
::
sage: 1 + a
2
"""
Whereas for example in tutorial/interface.rst you have a bunch of
"""
.. link
::
"""
without "::" after link. Moreover if you put a :: things seems to works
correctly but sphinx issues a
"""
/home/florent/src/Sage/sage/devel/sage/doc/en/reference/demos/tutorial-objects-and-classes.rst:56: (ERROR/3) Unknown directive type "link".
.. link::
"""
Should we correct the dev-guide ? If yes as a punishment for not having fully
read it, I'm ok to write a patch.
Cheers,
Florent
John H Palmieri
On Jan 16, 1:14 am, Florent Hivert <florent.hiv...@univ-rouen.fr>
wrote:
> Hi John,
> It seems that doesn't work inside a note environement:
know, the ".. link" directive is a Sage add-on, dealt with in
SAGE_ROOT/local/bin/sage-doctest, and it may not be implemented as
fully as one might like. Another way of looking at this is, perhaps
you should only be able to link blocks which are at the same level of
indentation, so maybe this is a feature, not a bug :)
> Another remark:
> In conventions.html#testing-rest-documentation you write
>
> """
> environments, use the ``.. link::`` comment.
>
> """
> .. link
>
> ::
> """
>
> without "::" after link. Moreover if you put a :: things seems to works
> correctly but sphinx issues a
>
> """
> .. link::
> """
>
> Should we correct the dev-guide ? If yes as a punishment for not having fully
> read it, I'm ok to write a patch.
give the warning). The same might be true with
"""
.. skip
::
"""
vs.
"""
.. skip::
"""
If you have time to write patch for the documentation, and if you
could check "skip", that would be great. Of course, cc me on any
ticket.
Thanks,
John
pang
I'm also interested in this feature: how about we add a single line at
the beggining of the rst file that indicates that all code cells are
linked? That would cover all my use cases: how about yours?
pang
Anyway, Florent, I'll talk to you about this tomorrow if we get a
chance.
Florent Hivert
I don't think 2 days in old for a thread ;-)
Florent
Jason Grout
That's a cool idea. +1, if it's possible.
Jason
Florent Hivert
Reviving an old thread.
> Before the second code block, you need a "link" directive to tell it
> that it should be connected with the previous block. See
>
> <http://sagemath.org/doc/developer/conventions.html#testing-rest-
> documentation>
>
> for documentation. For an example, see the file "interfaces.rst" in
> the tutorial. Your example could look like this:
>
>
> Examples of code::
>
> sage: el = 1
> sage: el
> 1
>
> Some explanations:
>
> .. link
>
> ::
>
> sage: el
> 1
>
> > It seems that doesn't work inside a note environement:
>
> I guess it doesn't interact well with other environments? As far as I
> know, the ".. link" directive is a Sage add-on, dealt with in
> SAGE_ROOT/local/bin/sage-doctest, and it may not be implemented as
> fully as one might like. Another way of looking at this is, perhaps
> you should only be able to link blocks which are at the same level of
> indentation, so maybe this is a feature, not a bug :)
I'm trying to improve this and I realize the following: To tests a .rst file
we convert it to a python file and send the resulting file to the usual
doctest infrastructure. If the .rst file contains:
blabla::
sage: x=1
more blabla::
sage: x
1
This is converted to something like
"""
sage: y=1
"""
"""
sage: y
1
"""
And the second test fails because y isn't defined.
One have to write
blabla::
sage: x=1
more blabla:
..link
::
sage: x
1
to have something like
"""
sage: y=1
sage: y
1
"""
which is correct. Is there any good reason why we do this complicated
transformation rather that simply put a pair of """ """ around the .rst file ?
Indeed sending
"""
blabla::
sage: x=1
more blabla::
sage: x
1
"""
perfectly works.
> I'm also interested in this feature: how about we add a single line at
> the beggining of the rst file that indicates that all code cells are
> linked? That would cover all my use cases: how about yours?
The following easy diff should solve the problem. (I'll put a patch in ticket
#11263 for it). But I don't see why we need to do something more complicated.
diff --git a/sage-doctest b/sage-doctest
--- a/sage-doctest
+++ b/sage-doctest
@@ -524,7 +524,10 @@ def pythonify_rst(F):
verbatim examples in the ReST file.
"""
import re
-
+
+ if '.. linkall' in F:
+ return '\n"""\n\n%s\n\n"""\n'%F
+
def get_next_verbatim_block(s, pos):
while True:
# regular expression search in string s[pos:] for:
Cheers,
Florent