Opened 9 years ago
Closed 9 years ago
#9608 closed defect (fixed)
Docbuild warnings in sage/interfaces/matlab.py
Reported by: | mpatel | Owned by: | mvngu |
---|---|---|---|
Priority: | blocker | Milestone: | sage-4.5.2 |
Component: | documentation | Keywords: | |
Cc: | ddrake, mhansen, rossk, leif | Merged in: | sage-4.5.2.rc0 |
Authors: | Mitesh Patel | Reviewers: | John Palmieri |
Report Upstream: | N/A | Work issues: | |
Branch: | Commit: | ||
Dependencies: | Stopgaps: |
Description
Docbuild warnings in Sage 4.5.2.alpha1:
$ ./sage -docbuild all html -j [...] /mnt/usb1/scratch/mpatel/tmp/sage-4.5.2.alpha1/local/lib/python2.6/site-packages/sage/interfaces/matlab.py:docstring of sage.interfaces.matlab.Matlab.strip_answer:6: (WARNING/2) Block quote ends without a blank line; unexpected unindent. /mnt/usb1/scratch/mpatel/tmp/sage-4.5.2.alpha1/local/lib/python2.6/site-packages/sage/interfaces/matlab.py:docstring of sage.interfaces.matlab.Matlab.strip_answer:9: (WARNING/2) Block quote ends without a blank line; unexpected unindent. [...]
Possibly related ticket: #2119.
Attachments (1)
Change History (8)
Changed 9 years ago by
comment:1 Changed 9 years ago by
- Status changed from new to needs_review
comment:2 Changed 9 years ago by
A one-character patch! Nice.
It does get rid of the warning for me, but I'd like to understand why the docstring needs to be raw. How does that fix the unindent warning?
comment:3 follow-up: ↓ 4 Changed 9 years ago by
I think the problem with the original docstring is that the backslashes are not escaped, so perhaps Sphinx interprets the \n
s as newline characters and sees
"""
Returns the string s with Matlab's answer prompt removed.
EXAMPLES::
sage: s = '
ans =
2
'
sage: matlab.strip_answer(s)
' 2'
"""
Not using a raw string but replacing the \n
s with \\n
s should also work.
comment:4 in reply to: ↑ 3 Changed 9 years ago by
Replying to mpatel:
Not using a raw string but replacing the
\n
s with\\n
s should also work.
Hrm, doing that doesn't fix the problem -- the function then gets a string with no newlines, but with literal "\n" bits.
I'm almost certain that making the docstring raw is the right thing to do, but I'd like to have someone who knows more about doctesting and Sphinx look at this.
comment:5 Changed 9 years ago by
- Cc leif added
comment:6 Changed 9 years ago by
- Reviewers set to John Palmieri
- Status changed from needs_review to positive_review
Hrm, doing that doesn't fix the problem -- the function then gets a string with no newlines, but with literal "\n" bits.
Isn't that what you want? You're defining s to be a particular string, one containing "\n" in it (to give a newline), and you want each "\n" to appear as such in the reference manual. That is, s = '\nans =\n\n 2\n'
is a valid way to define a python string, and it should appear this way in the reference manual. If you want to define a string containing actual new lines, you would have to use triple quotes, wouldn't you?
This makes sense to me, and I've seen other docstring errors and fixes just like this in the past. The particular docstring here looks much better after the patch, and there are no warnings. Positive review.
comment:7 Changed 9 years ago by
- Merged in set to sage-4.5.2.rc0
- Resolution set to fixed
- Status changed from positive_review to closed
Make the docstring raw