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)

trac_9608-matlab_docbuild.patch (613 bytes) - added by mpatel 9 years ago.
Make the docstring raw

Download all attachments as: .zip

Change History (8)

Changed 9 years ago by mpatel

Make the docstring raw

comment:1 Changed 9 years ago by mpatel

  • Authors set to Mitesh Patel
  • Status changed from new to needs_review

comment:2 Changed 9 years ago by ddrake

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: Changed 9 years ago by mpatel

I think the problem with the original docstring is that the backslashes are not escaped, so perhaps Sphinx interprets the \ns 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 \ns with \\ns should also work.

comment:4 in reply to: ↑ 3 Changed 9 years ago by ddrake

Replying to mpatel:

Not using a raw string but replacing the \ns with \\ns 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 leif

  • Cc leif added

comment:6 Changed 9 years ago by jhpalmieri

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

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