Docbuild warnings in sage/interfaces/matlab.py

[qed777]

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.

CC: @dandrake @mwhansen @sagetrac-rossk @nexttime

Component: documentation

Author: Mitesh Patel

Reviewer: John Palmieri

Merged: sage-4.5.2.rc0

Issue created by migration from https://trac.sagemath.org/ticket/9608

[qed777]

Attachment: trac_9608-matlab_docbuild.patch.gz

Make the docstring raw

[qed777]

Author: Mitesh Patel

[dandrake]

comment:2

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?

[qed777]

comment:3

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.

[dandrake]

comment:4

Replying to @qed777:

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.

[jhpalmieri]

comment:6

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.

[jhpalmieri]

Reviewer: John Palmieri

[qed777]

Merged: sage-4.5.2.rc0