Opened 12 years ago

Closed 11 years ago

#4689 closed defect (fixed)

save method for graphics objects does not have an example explicitly using "save"

Reported by: ljpk Owned by: tba
Priority: minor Milestone: sage-4.3.2
Component: documentation Keywords:
Cc: mhansen Merged in: sage-4.3.2.alpha0
Authors: Jason Grout Reviewers: Mike Hansen
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description

The examples in the documentation for the save method seems to be broken. If I try

sage: E=EllipticCurve([1,0])
sage: Eplot=E.plot()
sage: Eplot.save?

then I get

EXAMPLES:
                sage: c = circle((1,1),1,rgbcolor=(1,0,0))
                sage: c.show(xmin=-1,xmax=3,ymin=-1,ymax=3)

                To correct the apect ratio of certain graphics, it is necessary
                to show with a 'figsize' of square dimensions.

                sage: c.show(figsize=[5,5],xmin=-1,xmax=3,ymin=-1,ymax=3)

                sage: point((-1,1),pointsize=30, rgbcolor=(1,0,0))

which never mentions "save" at all. Presumably there should be an extra line, something like

sage: c.save("example.png")

Attachments (1)

trac-4689-save-docstring.patch (1.5 KB) - added by jason 11 years ago.

Download all attachments as: .zip

Change History (11)

comment:1 Changed 12 years ago by mabshoff

Hi,

which Sage release is that? If it is 3.2.1 this might be #4672. There is a patch over there that needs one doctest fix to be merged into 3.2.2.

Cheers,

Michael

comment:2 Changed 12 years ago by mabshoff

  • Component changed from algebra to documentation
  • Owner changed from tbd to tba

comment:3 Changed 12 years ago by ljpk

It's in both 3.1.4 and 3.2.1, but that bug report does look relevant; hopefully fixing that will sort this out too.

comment:4 Changed 12 years ago by mabshoff

  • Cc mhansen added
  • Summary changed from Documentation documenting the wrong thing to Improve docstring for save for graphics objects

With #4672 appplied:

mabshoff@sage:/scratch/mabshoff/release-cycle/sage-3.2.2.alpha0$ ./sage
----------------------------------------------------------------------
| Sage Version 3.2.1, Release Date: 2008-12-01                       |
| Type notebook() for the GUI, and license() for information.        |
----------------------------------------------------------------------
sage: E=EllipticCurve([1,0])
sage: Eplot=E.plot()
sage: Eplot.save?

results in

Type:           instancemethod
Base Class:     <type 'instancemethod'>
String Form:    <bound method Graphics.save of >
Namespace:      Interactive
File:           /scratch/mabshoff/release-cycle/sage-3.2.2.alpha0/local/lib/python2.5/site-packages/sage/plot/plot.py
Definition:     Eplot.save(self, filename=None, xmin=None, xmax=None, ymin=None, ymax=None, figsize=(6, 3.7082039324993699), figure=None, sub=None, savenow=True, dpi=100, axes=None, axes_labels=None, fontsize=None, frame=False, verify=True, aspect_ratio=None, gridlines=None, gridlinesstyle=None, vgridlinesstyle=None, hgridlinesstyle=None)
Docstring:
    
            Save the graphics to an image file of type: PNG, PS, EPS, SVG, SOBJ,
            depending on the file extension you give the filename.
                Extension types can be: file{.png}, file{.ps}, file{.eps}, file{.svg},
                and file{.sobj} (for a SAGE object you can load later). 
    
            EXAMPLES:
                sage: c = circle((1,1),1,rgbcolor=(1,0,0))
                sage: c.show(xmin=-1,xmax=3,ymin=-1,ymax=3)
    
                To correct the apect ratio of certain graphics, it is necessary
                to show with a 'figsize' of square dimensions.
    
                sage: c.show(figsize=[5,5],xmin=-1,xmax=3,ymin=-1,ymax=3)
                
                sage: point((-1,1),pointsize=30, rgbcolor=(1,0,0))

Rereading the original ticket I now get your main point: the docstring does not contain "save", but "show" does save the png and then pops up a viewer. We could resolve this by adding a example that uses the save method as you suggested, but my guess would be that such example (in case it did exist) was either changed or removed since "save('foo.png')" saves in the current working directory which is bad for doctesting as a non-owner.

So, what do you want to do? Close this ticket as "wontfix" or we add a doctest that saves an image in SAGE_TMP - which is the clean way to deal with temporary files.

Cheers,

Michael

comment:5 Changed 12 years ago by ljpk

I think your idea of having a doctest which saves an image somewhere temporary would be the best idea as it would give the reader the idea of how to use the method and reassure them that it is the correct help function.

comment:6 Changed 11 years ago by jason

  • Summary changed from Improve docstring for save for graphics objects to save method for graphics objects does not have an example explicitly using "save"

Changed 11 years ago by jason

comment:7 Changed 11 years ago by jason

  • Report Upstream set to N/A
  • Status changed from new to needs_review

comment:8 Changed 11 years ago by jason

  • Authors set to Jason Grout

comment:9 Changed 11 years ago by mhansen

  • Reviewers set to Mike Hansen
  • Status changed from needs_review to positive_review

Looks good to me.

comment:10 Changed 11 years ago by mvngu

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