plugin user API snippets

* along with test coverage for all snippets (using different data though)

docs/conf.py

@@ -52,7 +52,8 @@
     'sphinx.ext.napoleon',
     'sphinx_automodapi.automodapi',
     'sphinx.ext.mathjax',
-    'sphinx_design']
+    'sphinx_design',
+    'sphinx_togglebutton']
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']

docs/plugins.rst

@@ -13,6 +13,25 @@ If the data is loaded from multi-extension FITS that contains a primary header,
 you will also see a :guilabel:`Show primary header` toggle, when enabled, would
 display just the primary header metadata.
 
+
+.. admonition:: User API Example
+    :class: dropdown
+
+    .. 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()
+
+      metadata = lcviz.plugins['Metadata Viewer']
+      print(f"dataset choices: {metadata.dataset.choices}")
+      metadata.dataset = metadata.dataset.choices[0]
+      print(metadata.metadata)
+      
+
 .. seealso::
 
     :ref:`Jdaviz Metadata Viewer <jdaviz:imviz_metadata-viewer>`
@@ -25,6 +44,29 @@ Plot Options
 
 This plugin gives access to per-viewer and per-layer plotting options.
 
+
+.. admonition:: User API Example
+    :class: dropdown
+
+    .. 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()
+
+      po = lcviz.plugins['Plot Options']
+      print(f"viewer choices: {po.viewer.choices}")
+      po.viewer = po.viewer.choices[0]
+      print(f"layer choices: {po.layer.choices}")
+      po.layer = po.layer.choices[0]
+
+      po.marker_size = 4
+      po.marker_color = 'blue'
+
+
 .. seealso::
 
     :ref:`Jdaviz Plot Options <jdaviz:imviz-plot-options>`
@@ -55,11 +97,33 @@ displayed in the app toolbar into the table.  The markers remain at that fixed p
 the viewer they were created (regardless of changes to the underlying data or linking) and are only
 visible when the plugin is opened.
 
+
+.. admonition:: User API Example
+    :class: dropdown
+
+    .. 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()
+
+      markers = lcviz.plugins['Markers']
+      markers.open_in_tray()
+      # interactively mark by mousing over the viewer and pressing "M"
+      table = markers.export_table()
+      print(table)
+      markers.clear_table()
+
+
 .. seealso::
 
     :ref:`Jdaviz Markers <jdaviz:markers-plugin>`
         Jdaviz documentation on the Markers plugin.
 
+
 .. _flatten:
 
 Flatten
@@ -69,6 +133,25 @@ This plugin allows for flattening the light curve by removing trends.  By defaul
 "unnormalized" by multiplying the flattened light curve by the median of the trend, but this
 can be disabled through the plugin settings.
 
+.. admonition:: User API Example
+    :class: dropdown
+
+    .. code-block:: python
+
+      from lcviz import LCviz
+      lc = search_lightcurve("HAT-P-11", mission="Kepler",
+                             cadence="long", quarter=10).download()
+      lcviz = LCviz()
+      lcviz.load_data(lc)
+      lcviz.show()
+
+      flatten = lcviz.plugins['Flatten']
+      flatten.open_in_tray()
+      flatten.polyorder = 4
+      flattened_lc = flatten.flatten(add_data=True)
+      print(flattened_lc)
+
+
 .. seealso::
 
     This plugin uses the following ``lightkurve`` implementations:
@@ -83,6 +166,27 @@ Frequency Analysis
 
 This plugin exposes the periodogram (in period or frequency space) for an input light curve.
 
+
+.. admonition:: User API Example
+    :class: dropdown
+
+    .. 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()
+      
+      freq = lcviz.plugins['Frequency Analysis']
+      freq.open_in_tray()
+      freq.method = 'Lomb-Scargle'
+      freq.xunit = 'period'
+      periodogram = freq.periodogram
+      print(periodogram)
+
+
 .. seealso::
 
     This plugin uses the following ``lightkurve`` implementations:
@@ -100,13 +204,48 @@ The ephemeris plugin allows for setting, finding, and refining the ephemeris or
 for phase-folding.
 
 
+.. admonition:: User API Example
+    :class: dropdown
+
+    .. 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()
+
+      ephem = lcviz.plugins['Ephemeris']
+      ephem.period = 4.88780258
+      ephem.t0 = 2.43
+      ephem.rename_component('default', 'my component name')
+
+
 .. _export-plot:
 
 Export Plot
 ===========
 
 This plugin allows exporting the plot in a given viewer to various image formats.
 
+
+.. admonition:: User API Example
+    :class: dropdown
+
+    .. 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()
+
+      export = lcviz.plugins['Export Plot']
+      export.save_figure('test.png')
+
+
 .. seealso::
 
     :ref:`Jdaviz Export Plot <jdaviz:imviz-export-plot>`

lcviz/tests/test_plugin_ephemeris.py

@@ -1,3 +1,13 @@
+def test_docs_snippets(helper, light_curve_like_kepler_quarter):
+    lcviz, lc = helper, light_curve_like_kepler_quarter
+
+    lcviz.load_data(lc)
+    # lcviz.show()
+
+    ephem = lcviz.plugins['Ephemeris']
+    ephem.period = 4.88780258
+    ephem.t0 = 2.43
+    ephem.rename_component('default', 'my component name')
 
 
 def test_plugin_ephemeris(helper, light_curve_like_kepler_quarter):

lcviz/tests/test_plugin_flatten.py

@@ -10,6 +10,19 @@ def _get_marks_from_viewer(viewer, cls=(LivePreviewTrend, LivePreviewFlattened),
             if include_not_visible or m.visible]
 
 
+def test_docs_snippets(helper, light_curve_like_kepler_quarter):
+    lcviz, lc = helper, light_curve_like_kepler_quarter
+
+    lcviz.load_data(lc)
+    # lcviz.show()
+
+    flatten = lcviz.plugins['Flatten']
+    flatten.open_in_tray()
+    flatten.polyorder = 4
+    flattened_lc = flatten.flatten(add_data=True)
+    print(flattened_lc)
+
+
 def test_plugin_flatten(helper, light_curve_like_kepler_quarter):
     helper.load_data(light_curve_like_kepler_quarter)
     tv = helper.app.get_viewer(helper._default_time_viewer_reference_name)

lcviz/tests/test_plugin_frequency_analysis.py

@@ -3,6 +3,20 @@
 from lightkurve.periodogram import LombScarglePeriodogram, BoxLeastSquaresPeriodogram
 
 
+def test_docs_snippets(helper, light_curve_like_kepler_quarter):
+    lcviz, lc = helper, light_curve_like_kepler_quarter
+
+    lcviz.load_data(lc)
+    # lcviz.show()
+
+    freq = lcviz.plugins['Frequency Analysis']
+    freq.open_in_tray()
+    freq.method = 'Lomb-Scargle'
+    freq.xunit = 'period'
+    periodogram = freq.periodogram
+    print(periodogram)
+
+
 def test_plugin_frequency_analysis(helper, light_curve_like_kepler_quarter):
     helper.load_data(light_curve_like_kepler_quarter)
     # tv = helper.app.get_viewer(helper._default_time_viewer_reference_name)

lcviz/tests/test_plugin_markers.py

@@ -19,6 +19,20 @@ def _assert_dict_allclose(dict1, dict2):
             assert v == dict2.get(k)
 
 
+def test_docs_snippets(helper, light_curve_like_kepler_quarter):
+    lcviz, lc = helper, light_curve_like_kepler_quarter
+
+    lcviz.load_data(lc)
+    # lcviz.show()
+
+    markers = lcviz.plugins['Markers']
+    markers.open_in_tray()
+    # interactively mark by mousing over the viewer and pressing "M"
+    table = markers.export_table()
+    print(table)
+    markers.clear_table()
+
+
 def test_plugin_markers(helper, light_curve_like_kepler_quarter):
     helper.load_data(light_curve_like_kepler_quarter)
     tv = helper.app.get_viewer(helper._default_time_viewer_reference_name)

lcviz/tests/test_plugin_metadata.py

@@ -0,0 +1,10 @@
+def test_docs_snippets(helper, light_curve_like_kepler_quarter):
+    lcviz, lc = helper, light_curve_like_kepler_quarter
+
+    lcviz.load_data(lc)
+    # lcviz.show()
+
+    metadata = lcviz.plugins['Metadata Viewer']
+    print(f"dataset choices: {metadata.dataset.choices}")
+    metadata.dataset = metadata.dataset.choices[0]
+    print(metadata.metadata)

lcviz/tests/test_plugin_plot_options.py

@@ -0,0 +1,14 @@
+def test_docs_snippets(helper, light_curve_like_kepler_quarter):
+    lcviz, lc = helper, light_curve_like_kepler_quarter
+
+    lcviz.load_data(lc)
+    # lcviz.show()
+
+    po = lcviz.plugins['Plot Options']
+    print(f"viewer choices: {po.viewer.choices}")
+    po.viewer = po.viewer.choices[0]
+    print(f"layer choices: {po.layer.choices}")
+    po.layer = po.layer.choices[0]
+
+    po.marker_size = 4
+    po.marker_color = 'blue'

pyproject.toml

@@ -46,7 +46,8 @@ test = [
 ]
 docs = [
     "sphinx-astropy[confv2]>=1.9.1",
-    "sphinx_design"
+    "sphinx_design",
+    "sphinx-togglebutton"
 ]
 
 [build-system]