Improve plugin API docs (#84)

* fix link to flux column API docs
* populate missing API docs for plugin user APIs
* add user-API example for subset-tools - currently just opens in tray since now other exposed API yet
* fix broken API links to upstream
* link upstream for accessing plugin APIs

docs/plugins.rst

@@ -47,7 +47,7 @@ This plugin allows choosing which column in the underlying data should be used a
 .. admonition:: User API Example
     :class: dropdown
 
-    See the :class:`~lcviz.plugins.plot_options.plot_options.PlotOptions` user API documentation for more details.
+    See the :class:`~lcviz.plugins.flux_column.flux_column.FluxColumn` user API documentation for more details.
 
     .. code-block:: python
 
@@ -114,6 +114,24 @@ Subset Tools
 
 This plugin allows viewing and modifying defined subsets.
 
+.. admonition:: User API Example
+    :class: dropdown
+
+    See the :class:`~lcviz.plugins.subset_plugin.subset_plugin.SubsetPlugin` user API documentation for more details.
+
+    .. code-block:: python
+
+      from lcviz import LCviz
+      lc = search_lightcurve("HAT-P-11", mission="Kepler",
+                             cadence="long", quarter=10).download().flatten()
+      lcviz = LCviz()
+      lcviz.load_data(lc)
+      lcviz.show()
+
+      subset_tools = lcviz.plugins['Subset Tools']
+      subset_tools.open_in_tray()
+
+
 .. seealso::
 
     :ref:`Jdaviz Subset Tools <jdaviz:imviz-subset-plugin>`

lcviz/plugins/binning/binning.py

@@ -31,15 +31,18 @@ class Binning(PluginTemplateMixin, FluxColumnSelectMixin, DatasetSelectMixin,
     See the :ref:`Binning Plugin Documentation <binning>` for more details.
 
     Only the following attributes and methods are available through the
-    public plugin API.
+    :ref:`public plugin API <plugin-apis>`:
 
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.show`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.open_in_tray`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.close_in_tray`
     * ``dataset`` (:class:`~jdaviz.core.template_mixin.DatasetSelect`):
       Dataset to bin.
     * ``ephemeris`` (:class:`~jdaviz.core.template_mixin.SelectPluginComponent`):
       Label of the component corresponding to the active ephemeris.
     * :meth:`input_lc`
       Data used as input to binning, based on ``dataset`` and ``ephemeris``.
-    * ``n_bins``
+    * ``n_bins`` : int
     * ``add_results`` (:class:`~jdaviz.core.template_mixin.AddResults`)
     * :meth:`bin`
     """

lcviz/plugins/ephemeris/ephemeris.py

@@ -30,17 +30,20 @@ class Ephemeris(PluginTemplateMixin, DatasetSelectMixin):
     See the :ref:`Ephemeris Plugin Documentation <ephemeris>` for more details.
 
     Only the following attributes and methods are available through the
-    public plugin API.
+    :ref:`public plugin API <plugin-apis>`:
 
-    * ``component`` (:class:`~jdaviz.template_mixin.EditableSelectPluginComponent`):
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.show`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.open_in_tray`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.close_in_tray`
+    * ``component`` (:class:`~jdaviz.core.template_mixin.EditableSelectPluginComponent`):
       Label of the component corresponding to the active ephemeris.
-    * :attr:`t0`:
+    * :attr:`t0` : float
       Zeropoint of the ephemeris.
-    * :attr:`period`:
+    * :attr:`period` : float
       Period of the ephemeris, defined at ``t0``.
-    * :attr:`dpdt`:
+    * :attr:`dpdt` : float
       First derivative of the period of the ephemeris.
-    * :attr:`wrap_at`:
+    * :attr:`wrap_at` : float
       Phase at which to wrap (phased data will encompass the range 1-wrap_at to wrap_at).
     * :meth:`ephemeris`
     * :meth:`ephemerides`
@@ -53,7 +56,7 @@ class Ephemeris(PluginTemplateMixin, DatasetSelectMixin):
     * :meth:`get_data`
     * ``dataset`` (:class:`~jdaviz.core.template_mixin.DatasetSelect`):
       Dataset to use for determining the period.
-    * ``method`` (:class:`~jdaviz.core.template_mixing.SelectPluginComponent`):
+    * ``method`` (:class:`~jdaviz.core.template_mixin.SelectPluginComponent`):
       Method/algorithm to determine the period.
     """
     template_file = __file__, "ephemeris.vue"

lcviz/plugins/export_plot/export_plot.py

@@ -6,6 +6,19 @@
 
 @tray_registry('lcviz-export-plot', label="Export Plot")
 class ExportViewer(ExportViewer):
+    """
+    See the :ref:`Export Plot Plugin Documentation <export-plot>` for more details.
+
+    Only the following attributes and methods are available through the
+    :ref:`public plugin API <plugin-apis>`:
+
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.show`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.open_in_tray`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.close_in_tray`
+    * ``viewer`` (:class:`~jdaviz.core.template_mixin.ViewerSelect`):
+      Viewer to select for exporting the figure image.
+    * :meth:`save_figure`
+    """
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.docs_link = f"https://lcviz.readthedocs.io/en/{self.vdocs}/plugins.html#export-plot"

lcviz/plugins/flatten/flatten.py

@@ -28,20 +28,23 @@ class Flatten(PluginTemplateMixin, FluxColumnSelectMixin, DatasetSelectMixin):
     See the :ref:`Flatten Plugin Documentation <flatten>` for more details.
 
     Only the following attributes and methods are available through the
-    public plugin API.
+    :ref:`public plugin API <plugin-apis>`:
 
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.show`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.open_in_tray`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.close_in_tray`
     * ``show_live_preview`` : bool
         Whether to show the live-preview of the (unnormalized) flattened light curve
     * ``show_trend_preview`` : bool
         Whether to show the live-preview of the trend curve used to flatten the light curve
     * ``dataset`` (:class:`~jdaviz.core.template_mixin.DatasetSelect`):
       Dataset to flatten.
-    * ``window_length``
-    * ``polyorder``
-    * ``break_tolerance``
-    * ``niters``
-    * ``sigma``
-    * ``unnormalize``
+    * ``window_length`` : int
+    * ``polyorder`` : int
+    * ``break_tolerance`` : int
+    * ``niters`` : int
+    * ``sigma`` : float
+    * ``unnormalize`` : bool
     * ``flux_label`` (:class:`~jdaviz.core.template_mixin.AutoTextField`):
       Label for the resulting flux column added to ``dataset`` and automatically selected as the new
       flux column (origin).

lcviz/plugins/flux_column/flux_column.py

@@ -14,8 +14,11 @@ class FluxColumn(PluginTemplateMixin, FluxColumnSelectMixin, DatasetSelectMixin)
     See the :ref:`Flux Column Plugin Documentation <flux-column>` for more details.
 
     Only the following attributes and methods are available through the
-    public plugin API.
+    :ref:`public plugin API <plugin-apis>`:
 
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.show`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.open_in_tray`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.close_in_tray`
     * ``dataset`` (:class:`~jdaviz.core.template_mixin.DatasetSelect`):
       Dataset to bin.
     * ``flux_column`` (:class:`~lcviz.components.FluxColumnSelect`)

lcviz/plugins/frequency_analysis/frequency_analysis.py

@@ -22,17 +22,20 @@ class FrequencyAnalysis(PluginTemplateMixin, DatasetSelectMixin, PlotMixin):
     See the :ref:`Frequency Analysis Plugin Documentation <frequency_analysis>` for more details.
 
     Only the following attributes and methods are available through the
-    public plugin API.
+    :ref:`public plugin API <plugin-apis>`:
 
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.show`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.open_in_tray`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.close_in_tray`
     * ``dataset`` (:class:`~jdaviz.core.template_mixin.DatasetSelect`):
       Dataset to use for analysis.
-    * ``method`` (:class:`~jdaviz.core.template_mixing.SelectPluginComponent`):
+    * ``method`` (:class:`~jdaviz.core.template_mixin.SelectPluginComponent`):
       Method/algorithm to determine the period.
-    * ``xunit`` (:class:`~jdaviz.core.template_mixing.SelectPluginComponent`):
+    * ``xunit`` (:class:`~jdaviz.core.template_mixin.SelectPluginComponent`):
       Whether to plot power vs fequency or period.
-    * ``auto_range``
-    * ``minimum``
-    * ``maximum``
+    * ``auto_range`` : bool
+    * ``minimum`` : float
+    * ``maximum`` : float
     * :meth:``periodogram``
     """
     template_file = __file__, "frequency_analysis.vue"

lcviz/plugins/markers/markers.py

@@ -8,6 +8,18 @@
 
 @tray_registry('lcviz-markers', label="Markers")
 class Markers(Markers):
+    """
+    See the :ref:`Markers Plugin Documentation <markers>` for more details.
+
+    Only the following attributes and methods are available through the
+    :ref:`public plugin API <plugin-apis>`:
+
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.show`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.open_in_tray`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.close_in_tray`
+    * :meth:`clear_table`
+    * :meth:`~jdaviz.core.template_mixin.TableMixin.export_table`
+    """
     _default_table_values = {'time': np.nan,
                              'phase': np.nan,
                              'ephemeris': '',

lcviz/plugins/metadata_viewer/metadata_viewer.py

@@ -6,6 +6,25 @@
 
 @tray_registry('lcviz-metadata-viewer', label="Metadata")
 class MetadataViewer(MetadataViewer):
+    """
+    See the :ref:`Metadata Viewer Plugin Documentation <metadata-viewer>` for more details.
+
+    Only the following attributes and methods are available through the
+    :ref:`public plugin API <plugin-apis>`:
+
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.show`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.open_in_tray`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.close_in_tray`
+    * ``dataset`` (:class:`~jdaviz.core.template_mixin.DatasetSelect`):
+      Dataset to expose the metadata.
+    * :attr:`show_primary` : bool
+      Whether to show MEF primary header metadata instead.
+    * :attr:`metadata`:
+      Read-only metadata. If the data is loaded from a multi-extension FITS file,
+      this can be the extension header or the primary header, depending on
+      ``show_primary`` setting.
+
+    """
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.docs_link = f"https://lcviz.readthedocs.io/en/{self.vdocs}/plugins.html#metadata-viewer"  # noqa

lcviz/plugins/plot_options/plot_options.py

@@ -6,18 +6,43 @@
 
 @tray_registry('lcviz-plot-options', label="Plot Options")
 class PlotOptions(PlotOptions):
+    """
+    See the :ref:`Plot Options Plugin Documentation <plot-options>` for more details.
+
+    For a full list of exposed attributes, call ``dir(plugin)``.  Note that some attributes are
+    applicable depending on the selection of ``viewer`` and/or ``layer``.  Below are
+    a list of some common attributes and methods are available through the
+    :ref:`public plugin API <plugin-apis>`:
+
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.show`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.open_in_tray`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.close_in_tray`
+    * ``viewer`` (:class:`~jdaviz.core.template_mixin.ViewerSelect`):
+    * ``viewer_multiselect``
+    * ``layer`` (:class:`~jdaviz.core.template_mixin.LayerSelect`):
+    * ``layer_multiselect``
+    * :meth:`select_all`
+    * ``subset_color`` (:class:`~jdaviz.core.template_mixin.PlotOptionsSyncState`):
+    * ``line_color`` (:class:`~jdaviz.core.template_mixin.PlotOptionsSyncState`):
+    * ``line_width`` (:class:`~jdaviz.core.template_mixin.PlotOptionsSyncState`):
+    * ``line_opacity`` (:class:`~jdaviz.core.template_mixin.PlotOptionsSyncState`):
+    """
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.docs_link = f"https://lcviz.readthedocs.io/en/{self.vdocs}/plugins.html#plot-options"
 
     @property
     def user_api(self):
         api = super().user_api
-        api._expose += ['marker_visible', 'marker_fill', 'marker_opacity',
-                        'marker_size_mode', 'marker_size', 'marker_size_scale',
-                        'marker_size_col', 'marker_size_vmin', 'marker_size_vmax',
-                        'marker_color_mode', 'marker_color', 'marker_color_col',
-                        'marker_colormap', 'marker_colormap_vmin', 'marker_colormap_vmax',
-                        'line_visible', 'line_width']
+        expose = [e for e in api._expose if e not in ('apply_RGB_presets', 'line_as_steps',
+                  'uncertainty_visible')]
+
+        expose += ['marker_visible', 'marker_fill', 'marker_opacity',
+                   'marker_size_mode', 'marker_size', 'marker_size_scale',
+                   'marker_size_col', 'marker_size_vmin', 'marker_size_vmax',
+                   'marker_color_mode', 'marker_color', 'marker_color_col',
+                   'marker_colormap', 'marker_colormap_vmin', 'marker_colormap_vmax',
+                   'line_visible', 'line_width']
+        api._expose = expose
 
         return api

lcviz/plugins/subset_plugin/subset_plugin.py

@@ -6,6 +6,16 @@
 
 @tray_registry('lcviz-subset-plugin', label="Subset Tools")
 class SubsetPlugin(SubsetPlugin):
+    """
+    See the :ref:`Subset Plugin Documentation <subset-tools>` for more details.
+
+    Only the following attributes and methods are available through the
+    :ref:`public plugin API <plugin-apis>`:
+
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.show`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.open_in_tray`
+    * :meth:`~jdaviz.core.template_mixin.PluginTemplateMixin.close_in_tray`
+    """
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.docs_link = f"https://lcviz.readthedocs.io/en/{self.vdocs}/plugins.html#subset-tools"