plotting: for user convenience, move the doc in the main API

Users only call the plot methods from the objects.
It's thus more convenient for them to have the doc there.
But it's more convenient for developers to have the doc alongside the code.

Other advantages:
* Default values are set in the main API (on graphs and filters objects).
* All parameters have to be named.

pygsp/__init__.py

@@ -30,5 +30,13 @@
 
 _utils.import_modules(__all__[::-1], 'pygsp', 'pygsp')
 
+# Users only call the plot methods from the objects.
+# It's thus more convenient for them to have the doc there.
+# But it's more convenient for developers to have the doc alongside the code.
+filters.Filter.plot.__doc__ = plotting._plot_filter.__doc__
+graphs.Graph.plot.__doc__ = plotting._plot_graph.__doc__
+graphs.Graph.plot_signal.__doc__ = plotting._plot_signal.__doc__
+graphs.Graph.plot_spectrogram.__doc__ = plotting._plot_spectrogram.__doc__
+
 __version__ = '0.5.1'
 __release_date__ = '2017-12-15'

pygsp/filters/filter.py

@@ -497,10 +497,9 @@ def can_dual_func(g, n, x):
 
         return Filter(self.G, kernels)
 
-    def plot(self, **kwargs):
-        r"""Plot the filter bank's frequency response.
-
-        See :func:`pygsp.plotting.plot_filter`.
-        """
-        from pygsp import plotting
-        plotting.plot_filter(self, **kwargs)
+    def plot(self, n=500, eigenvalues=None, sum=None, title='', save=None,
+             ax=None, **kwargs):
+        r"""Docstring overloaded at import time."""
+        from pygsp.plotting import _plot_filter
+        _plot_filter(self, n=n, eigenvalues=eigenvalues, sum=sum, title=title,
+                     save=save, ax=ax, **kwargs)

pygsp/graphs/graph.py

@@ -658,29 +658,26 @@ def modulate(self, f, k):
         fm *= np.sqrt(self.N)
         return fm
 
-    def plot(self, **kwargs):
-        r"""Plot the graph.
-
-        See :func:`pygsp.plotting.plot_graph`.
-        """
-        from pygsp import plotting
-        plotting.plot_graph(self, **kwargs)
-
-    def plot_signal(self, signal, **kwargs):
-        r"""Plot a signal on that graph.
-
-        See :func:`pygsp.plotting.plot_signal`.
-        """
-        from pygsp import plotting
-        plotting.plot_signal(self, signal, **kwargs)
-
-    def plot_spectrogram(self, **kwargs):
-        r"""Plot the graph's spectrogram.
-
-        See :func:`pygsp.plotting.plot_spectrogram`.
-        """
-        from pygsp import plotting
-        plotting.plot_spectrogram(self, **kwargs)
+    def plot(self, edges=None, backend=None, vertex_size=None, title=None,
+             save=None, ax=None):
+        r"""Docstring overloaded at import time."""
+        from pygsp.plotting import _plot_graph
+        _plot_graph(self, edges=edges, backend=backend,
+                    vertex_size=vertex_size, title=title, save=save, ax=ax)
+
+    def plot_signal(self, signal, edges=None, vertex_size=None, highlight=[],
+                    colorbar=True, limits=None, backend=None, title=None,
+                    save=None, ax=None):
+        r"""Docstring overloaded at import time."""
+        from pygsp.plotting import _plot_signal
+        _plot_signal(self, signal=signal, edges=edges, vertex_size=vertex_size,
+                     highlight=highlight, colorbar=colorbar, limits=limits,
+                     backend=backend, title=title, save=save, ax=ax)
+
+    def plot_spectrogram(self, node_idx=None):
+        r"""Docstring overloaded at import time."""
+        from pygsp.plotting import _plot_spectrogram
+        _plot_spectrogram(self, node_idx=node_idx)
 
     def _fruchterman_reingold_layout(self, dim=2, k=None, pos=None, fixed=[],
                                      iterations=50, scale=1.0, center=None,