Opened 12 years ago

Closed 11 years ago

#6572 closed defect (fixed)

[with patch, positive review] tutorial: put double colon on its own line

Reported by: mvngu Owned by: tba
Priority: major Milestone: sage-4.2
Component: documentation Keywords: tutorial
Cc: jhpalmieri, ncohen Merged in: sage-4.2.alpha0
Authors: John Palmieri Reviewers: Mike Hansen
Report Upstream: Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description (last modified by jhpalmieri)

See this sage-devel thread for some background information. John Palmieri suggests that all doctests in the Sage tutorial be preceded with a double colon on its own line. That way, the doctest script would pick up all doctests in the tutorial.

Depends on #6642 and #7149.

Attachments (4)

trac_6572_scripts.patch (2.5 KB) - added by jhpalmieri 12 years ago.
trac_6572-scripts-part2.patch (740 bytes) - added by jhpalmieri 11 years ago.
apply on top of other scripts patch
trac_6572-double-colon.patch (13.7 KB) - added by jhpalmieri 11 years ago.
depends on #6642
trac_6572-graphtheory.patch (4.6 KB) - added by jhpalmieri 11 years ago.
ignore this patch!

Download all attachments as: .zip

Change History (16)

comment:1 Changed 12 years ago by mvngu

  • Cc jhpalmieri added

comment:2 Changed 12 years ago by jhpalmieri

  • Summary changed from tutorial: put double colon on its own line to [with patch, needs review] tutorial: put double colon on its own line

Here are two patches, one for the main repository and one for the scripts repository.

The scripts patch does the following: first, previously, doctests had to be preceded by a double colon at the beginning of a line, and now they only need to be preceded by a line which starts with white space then a double colon -- the double colon no longer has to be at the left margin. This is important for some files (like constructions/algebraic_geometry.rst), in which indentations might break if we had to move the double colons to the left. The second change is figuring out when the doctest block ends: it looks for text indented no farther than the double colons were. (Previously, it looked for text which wasn't indented at all, so if a paragraph was indented, then some doctests were indented further, then a paragraph unindented one level, that second paragaph was treated as part of the doctest block.)

As a result of all of this, some more doctests are found by sage -t. The other patch does two things: it makes the change advertised in the summary for the ticket, moving double colons onto lines of their own where necessary. It also tries to fix the newly discovered broken doctests. I don't know how to fix some of these, and so they are being skipped. These include the one which triggered this whole episode:

     sage: theta = var('theta')
     sage: solve(cos(theta)==sin(theta))
     [sin(theta) == cos(theta)]

as well as some doctests involving starting and stopping the Singular console, for example.

For me, this passes all tests on Mac OS X (both 32-bit and 64-bit), and also on a 32-bit linux box (an old Ubuntu machine) and a 64-bit linux box (sage.math). It would be best to fix the skipped tests, but that can go in another ticket if no one knows how to do it right now.

Changed 12 years ago by jhpalmieri

comment:3 follow-up: Changed 11 years ago by jhpalmieri

See #6642 for the problem with the 'solve' doctest.

comment:4 in reply to: ↑ 3 Changed 11 years ago by kcrisman

Replying to jhpalmieri:

See #6642 for the problem with the 'solve' doctest.

This may be fixed now - see #6642. If so, I guess one could put that back in the tutorial.

comment:5 Changed 11 years ago by jhpalmieri

Here is a patch against 4.1.2.alpha1; this depends on #6642.

comment:6 follow-up: Changed 11 years ago by mhansen

Doesn't it make more sense to detect double colons at the end of a line?

In restructured text, the two should be equivalent. It should be the same for the doctests as well.

Changed 11 years ago by jhpalmieri

apply on top of other scripts patch

comment:7 in reply to: ↑ 6 Changed 11 years ago by jhpalmieri

  • Cc ncohen added

Replying to mhansen:

Doesn't it make more sense to detect double colons at the end of a line?

In restructured text, the two should be equivalent. It should be the same for the doctests as well.

Okay, that makes sense. The new scripts patch changes the regular expression to fix this, I think.

Now the problem is that the file (added since this ticket was opened) tour_graphtheory.rst is a *complete* disaster, with 15 doctest failures. I can fix lots of the failed doctests by adding "..." and ".. link" in various places, but I don't know what to do about failures like these:

    sage: g.plot(edge_colors=g.edge_coloring(hex_colors=True))
    AttributeError: 'Graph' object has no attribute 'edge_coloring'

    sage: g.vertex_coloring()
    AttributeError: 'Graph' object has no attribute 'vertex_coloring'

    sage: print g.max_matching()
    AttributeError: 'Graph' object has no attribute 'max_matching'

I don't know what was intended and therefore I don't know how to fix it. I'll post a patch that fixes what I can.

comment:8 Changed 11 years ago by jhpalmieri

I'll post a replacement for "trac_6572-double-colon.patch" soon. That patch shouldn't have to be as large, if double colons at the end of lines work right.

Changed 11 years ago by jhpalmieri

depends on #6642

comment:9 Changed 11 years ago by jhpalmieri

  • Summary changed from [with patch, needs review] tutorial: put double colon on its own line to [with patch, needs work] tutorial: put double colon on its own line

Here's a new version of "trac_6572-double-colon.patch". This fixes a few more doctest failures uncovered by the script patches. Apply both script patches, this patch, and the graph theory patch. Together with the patch at #6642, this means that most doctests pass in the documentation. tutorial/tour_graphtheory.rst is the only problem now.

comment:10 Changed 11 years ago by jhpalmieri

  • Description modified (diff)
  • Status changed from needs_work to needs_review
  • Summary changed from [with patch, needs work] tutorial: put double colon on its own line to [with patch, needs review] tutorial: put double colon on its own line

With the patch at #7149, this is now ready for review. Ignore the graph theory patch, since that is now taken care of by #7149.

Changed 11 years ago by jhpalmieri

ignore this patch!

comment:11 Changed 11 years ago by mhansen

  • Authors set to John Palmieri
  • Reviewers set to Mike Hansen
  • Status changed from needs_review to positive_review
  • Summary changed from [with patch, needs review] tutorial: put double colon on its own line to [with patch, positive review] tutorial: put double colon on its own line

Looks good to me.

comment:12 Changed 11 years ago by mhansen

  • Merged in set to sage-4.2.alpha0
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.