docstrings

Author: chriddyp

plotly/plotly/plotly.py

@@ -546,10 +546,25 @@ class image:
     """
     @staticmethod
     def get(figure_or_data, format='png', width=None, height=None, scale=None):
-        """
-        Return a static image of the plot described by `figure`.
+        """Return a static image of the plot described by `figure_or_data`.
 
-        Valid formats: 'png', 'svg', 'jpeg', 'pdf'
+        positional arguments:
+        - figure_or_data: The figure dict-like or data list-like object that
+                          describes a plotly figure.
+                          Same argument used in `py.plot`, `py.iplot`,
+                          see https://plot.ly/python for examples
+        - format: 'png', 'svg', 'jpeg', 'pdf'
+        - width: output width
+        - height: output height
+        - scale: Increase the resolution of the image by `scale` amount (e.g. `3`)
+               Only valid for PNG and JPEG images.
+
+        example:
+        ```
+        import plotly.plotly as py
+        fig = {'data': [{'x': [1, 2, 3], 'y': [3, 1, 5], 'type': 'bar'}]}
+        py.image.get(fig, 'png', scale=3)
+        ```
 
         """
         # TODO: format is a built-in name... we shouldn't really use it
@@ -625,10 +640,25 @@ def get(figure_or_data, format='png', width=None, height=None, scale=None):
     @classmethod
     def ishow(cls, figure_or_data, format='png', width=None, height=None,
               scale=None):
-        """
-        Display a static image of the plot described by `figure`
+        """Display a static image of the plot described by `figure_or_data`
         in an IPython Notebook.
 
+        positional arguments:
+        - figure_or_data: The figure dict-like or data list-like object that
+                          describes a plotly figure.
+                          Same argument used in `py.plot`, `py.iplot`,
+                          see https://plot.ly/python for examples
+        - format: 'png', 'svg', 'jpeg', 'pdf'
+        - width: output width
+        - height: output height
+        - scale: Increase the resolution of the image by `scale` amount
+               Only valid for PNG and JPEG images.
+
+        example:
+        ```
+        import plotly.plotly as py
+        fig = {'data': [{'x': [1, 2, 3], 'y': [3, 1, 5], 'type': 'bar'}]}
+        py.image.ishow(fig, 'png', scale=3)
         """
         if format == 'pdf':
             raise exceptions.PlotlyError(
@@ -647,13 +677,31 @@ def ishow(cls, figure_or_data, format='png', width=None, height=None,
     @classmethod
     def save_as(cls, figure_or_data, filename, format=None, width=None,
                 height=None, scale=None):
-        """
-        Save a image of the plot described by `figure` locally as `filename`.
+        """Save a image of the plot described by `figure_or_data` locally as
+        `filename`.
 
         Valid image formats are 'png', 'svg', 'jpeg', and 'pdf'.
         The format is taken as the extension of the filename or as the
         supplied format.
 
+        positional arguments:
+        - figure_or_data: The figure dict-like or data list-like object that
+                          describes a plotly figure.
+                          Same argument used in `py.plot`, `py.iplot`,
+                          see https://plot.ly/python for examples
+        - filename: The filepath to save the image to
+        - format: 'png', 'svg', 'jpeg', 'pdf'
+        - width: output width
+        - height: output height
+        - scale: Increase the resolution of the image by `scale` amount
+               Only valid for PNG and JPEG images.
+
+        example:
+        ```
+        import plotly.plotly as py
+        fig = {'data': [{'x': [1, 2, 3], 'y': [3, 1, 5], 'type': 'bar'}]}
+        py.image.save_as(fig, 'my_image.png', scale=3)
+        ```
         """
         # todo: format shadows built-in name
         (base, ext) = os.path.splitext(filename)