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 )
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.
Attachments (4)
Change History (16)
comment:1 Changed 12 years ago by
- Cc jhpalmieri added
comment:2 Changed 12 years ago by
- Summary changed from tutorial: put double colon on its own line to [with patch, needs review] tutorial: put double colon on its own line
Changed 12 years ago by
comment:3 follow-up: ↓ 4 Changed 11 years ago by
See #6642 for the problem with the 'solve' doctest.
comment:4 in reply to: ↑ 3 Changed 11 years ago by
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
Here is a patch against 4.1.2.alpha1; this depends on #6642.
comment:6 follow-up: ↓ 7 Changed 11 years ago by
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.
comment:7 in reply to: ↑ 6 Changed 11 years ago by
- 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
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.
comment:9 Changed 11 years ago by
- 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
- 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
comment:11 Changed 11 years ago by
- 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
- Merged in set to sage-4.2.alpha0
- Resolution set to fixed
- Status changed from positive_review to closed
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: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.