Testing rst files...

10 views
Skip to first unread message

Florent Hivert

unread,
Jan 15, 2011, 7:13:44 PM1/15/11
to Sage Devel
Hi there,

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

unread,
Jan 15, 2011, 10:14:19 PM1/15/11
to sage-devel
On Jan 15, 4:13 pm, Florent Hivert <florent.hiv...@univ-rouen.fr>
wrote:
>       Hi there,
>
> 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 ?

Yes, yes, and no.

> 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>

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".)

--
John

Florent Hivert

unread,
Jan 16, 2011, 3:53:27 AM1/16/11
to sage-...@googlegroups.com
Hi John,

> > 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

unread,
Jan 16, 2011, 4:14:39 AM1/16/11
to sage-...@googlegroups.com
Hi John,

> 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

unread,
Jan 16, 2011, 5:22:41 AM1/16/11
to sage-...@googlegroups.com
Another remark:

> 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

unread,
Jan 16, 2011, 11:37:25 AM1/16/11
to sage-devel


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:

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 :)

> Another remark:

> In conventions.html#testing-rest-documentation you write
>
> """
> environments, use the ``.. link::`` comment.

> 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-obje cts-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.

I think we should correct the dev guide (or patch Sphinx so it doesn't
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

unread,
Jan 17, 2011, 5:42:55 PM1/17/11
to sage-devel
Hello:

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

unread,
Jan 17, 2011, 5:45:42 PM1/17/11
to sage-devel
oops, sorry, for some weird reason I was looking at this old thread.
Anyway, Florent, I'll talk to you about this tomorrow if we get a
chance.

Florent Hivert

unread,
Jan 17, 2011, 7:24:10 PM1/17/11
to sage-...@googlegroups.com

I don't think 2 days in old for a thread ;-)

Florent

Jason Grout

unread,
Jan 17, 2011, 8:07:57 PM1/17/11
to sage-...@googlegroups.com

That's a cool idea. +1, if it's possible.

Jason


Florent Hivert

unread,
Apr 28, 2011, 5:52:09 PM4/28/11
to sage-...@googlegroups.com
Hi Sage fan,

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

Reply all
Reply to author
Forward
0 new messages