Adding example gallery + minor refactor of the doc layout (#113)

* adding example

* i dont know what I'm doing

* trying to add to index

* maybe this'll work

* arg

* tidy config

* redo examples

---------

Co-authored-by: Nabil Freij <nabil.freij@gmail.com>

.github/workflows/ci.yml

@@ -96,6 +96,17 @@ jobs:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   publish_pure:
+      # publish_pure will only publish if tagged ^v.*
+      if: |
+        (
+          github.event_name != 'pull_request' && (
+            github.ref_name != 'main' ||
+            github.event_name == 'workflow_dispatch'
+          )
+        ) || (
+          github.event_name == 'pull_request' &&
+          contains(github.event.pull_request.labels.*.name, 'Run publish')
+        )
       needs: [test, docs]
       uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish_pure_python.yml@main
       with:

.gitignore

@@ -238,12 +238,14 @@ $RECYCLE.BIN/
 # Windows shortcuts
 *.lnk
 
-### Extra Python Items and SunPy Specific
+### Extra Python Items and Package Specific
 docs/whatsnew/latest_changelog.txt
 examples/**/*.csv
 figure_test_images*
 tags
 baseline
+docs/generated/
+docs/sg_execution_times.rst
 
 # Release script
 .github_cache

.ruff.toml

@@ -63,18 +63,16 @@ lint.select = [
     "YTT",
 ]
 lint.extend-ignore = [
-    # TODO: Fix in future
-    "E501",  # Line too long
-    "E741",  # Ambiguous variable name
-    "FBT002", # Bool arg
     "COM812", # May cause conflicts when used with the formatter
     "ISC001",  # May cause conflicts when used with the formatter
 ]
 
 [lint.per-file-ignores]
 "examples/*.py" = [
-    "INP001", # examples is part of an implicit namespace package
-    "T201", # We need print in our examples
+    "INP001", # Implicit namespace package
+    "T201", # Use print
+    "B018", # Not print but display
+    "ERA001", # Commented out code
 ]
 "docs/conf.py" = [
     "INP001", # conf.py is part of an implicit namespace package

docs/api.rst

@@ -0,0 +1,4 @@
+Reference/API
+=============
+
+.. automodapi:: sunpy_soar

docs/coc.rst

@@ -0,0 +1,4 @@
+Code of Conduct
+===============
+
+When you are interacting with the SunPy community you are asked to follow our `Code of Conduct <https://sunpy.org/coc>`__.

docs/conf.py

@@ -8,6 +8,8 @@
 import datetime
 from pathlib import Path
 
+from sunpy_sphinx_theme import PNG_ICON
+
 from sunpy_soar import __version__
 
 project = "sunpy-soar"
@@ -18,6 +20,8 @@
 
 # -- General configuration ---------------------------------------------------
 extensions = [
+    "sphinx_gallery.gen_gallery",
+    "matplotlib.sphinxext.plot_directive",
     "sphinx_automodapi.automodapi",
     "sphinx_automodapi.smart_resolver",
     "sphinx_changelog",
@@ -90,3 +94,19 @@
         dtype, target = line.split(None, 1)
         target = target.strip()
         nitpick_ignore.append((dtype, target))
+
+# -- Options for the Sphinx gallery -------------------------------------------
+sphinx_gallery_conf = {
+    "backreferences_dir": Path("generated") / "modules",
+    "filename_pattern": "^((?!skip_).)*$",
+    "examples_dirs": Path("..") / "examples",
+    "gallery_dirs": Path("generated") / "gallery",
+    "matplotlib_animations": True,
+    # Comes from the theme.
+    "default_thumb_file": PNG_ICON,
+    "abort_on_example_error": False,
+    "plot_gallery": "True",
+    "remove_config_comments": True,
+    "doc_module": ("sunpy-soar"),
+    "only_warn_on_example_error": True,
+}

docs/index.rst

@@ -4,16 +4,11 @@
 
 A sunpy Fido plugin for accessing data in the Solar Orbiter Archive (SOAR).
 
-.. toctree::
-   :maxdepth: 1
-
-   changelog
-
 Installation
 ============
 
-``sunpy-soar`` requires ``python >= 3.9`` and ``sunpy >= 5.0``.
-Currently it can only be installed from PyPI using:
+``sunpy-soar`` requires ``python >= 3.10`` and ``sunpy >= 5.0``.
+Currently it can be installed from PyPI using:
 
 .. code-block:: bash
 
@@ -25,69 +20,6 @@ or conda using
 
    conda install -c conda-forge sunpy_soar
 
-Example
-=======
-
-The code below gives an example of how to search and download Solar Orbiter data using ``sunpy.net.Fido``:
-
-.. code-block:: python
-
-   # Importing sunpy_soar registers the client with sunpy
-   >>> import sunpy_soar
-   >>> from sunpy.net import Fido
-   >>> import sunpy.net.attrs as a
-
-   # Create search attributes
-   >>> instrument = a.Instrument('EUI')
-   >>> time = a.Time('2021-02-01', '2021-02-02')
-   >>> level = a.Level(1)
-   >>> product = a.soar.Product('EUI-FSI174-IMAGE')
-
-   # Do search
-   >>> result = Fido.search(instrument & time & level & product)
-   >>> print(result)
-   Results from 1 Provider:
-   <BLANKLINE>
-   43 Results from the SOARClient:
-   <BLANKLINE>
-   Instrument   Data product   Level        Start time               End time        Filesize SOOP Name
-                                                                                    Mbyte
-   ---------- ---------------- ----- ----------------------- ----------------------- -------- ---------
-         EUI eui-fsi174-image    L1 2021-02-01 00:45:12.228 2021-02-01 00:45:22.228    3.393      none
-         EUI eui-fsi174-image    L1 2021-02-01 01:15:12.232 2021-02-01 01:15:22.232    0.418      none
-         EUI eui-fsi174-image    L1 2021-02-01 01:45:12.237 2021-02-01 01:45:22.237    0.406      none
-         EUI eui-fsi174-image    L1 2021-02-01 02:15:12.238 2021-02-01 02:15:22.238    3.352      none
-         EUI eui-fsi174-image    L1 2021-02-01 02:45:12.241 2021-02-01 02:45:22.241    0.406      none
-         EUI eui-fsi174-image    L1 2021-02-01 03:15:12.244 2021-02-01 03:15:22.244    0.406      none
-         ...              ...   ...                     ...                     ...      ...       ...
-         EUI eui-fsi174-image    L1 2021-02-01 20:44:52.224 2021-02-01 20:45:02.224    0.409      none
-         EUI eui-fsi174-image    L1 2021-02-01 21:15:12.227 2021-02-01 21:15:22.227    3.387      none
-         EUI eui-fsi174-image    L1 2021-02-01 21:45:12.230 2021-02-01 21:45:22.230    0.412      none
-         EUI eui-fsi174-image    L1 2021-02-01 22:15:12.233 2021-02-01 22:15:22.233    0.415      none
-         EUI eui-fsi174-image    L1 2021-02-01 22:44:52.236 2021-02-01 22:45:02.236    0.423      none
-         EUI eui-fsi174-image    L1 2021-02-01 23:15:12.239 2021-02-01 23:15:22.239    3.459      none
-         EUI eui-fsi174-image    L1 2021-02-01 23:45:12.242 2021-02-01 23:45:22.242    0.415      none
-   Length = 43 rows
-   <BLANKLINE>
-   <BLANKLINE>
-
-   # Download files
-   >>> files = Fido.fetch(result)  # doctest: +SKIP
-   >>> print(files)  # doctest: +SKIP
-
-Available search attributes
-===========================
-
-The easiest way to access search attributes is using ``import sunpy.net.attrs as a``.
-When constructing a search for SOAR ``a.Time`` must be provided.
-Other search attributes can be used too - ``sunpy-soar`` recognises the following:
-
-- ``a.Instrument``
-- ``a.Level`` - one of ``L0, L1, L2, L3, LL01, LL02, LL03``
-- ``a.soar.Product``
-
-The third ``near`` argument to ``a.Time`` is not currently supported - you will have to manually filter the results if you want to find the one closest to a given time.
-
 ``sunpy-soar`` and the VSO
 ==========================
 
@@ -111,14 +43,12 @@ Contributing
 If you would like to get involved, start by joining the `SunPy Chat`_ and check out our `Newcomers' guide <https://docs.sunpy.org/en/latest/dev_guide/contents/newcomers.html>`__.
 This will walk you through getting set up for contributing.
 
-Code of Conduct
-===============
-
-When you are interacting with the SunPy community you are asked to follow our `Code of Conduct <https://sunpy.org/coc>`__.
-
 .. _SunPy Chat: https://app.element.io/#/room/#sunpy:openastronomy.org
 
-Reference/API
-=============
+.. toctree::
+   :hidden:
 
-.. automodapi:: sunpy_soar
+   generated/gallery/index
+   api
+   changelog
+   coc

examples/README.txt

@@ -0,0 +1,6 @@
+***************
+Example Gallery
+***************
+
+This gallery contains examples of how to use ``sunpy-soar``.
+

examples/quick.py

@@ -0,0 +1,37 @@
+"""
+============================================
+Quick overview of using sunpy-soar with Fido
+============================================
+
+This example demonstrates how to search and download Solar Orbiter data using ``sunpy.net.Fido``.
+"""
+
+import sunpy.net.attrs as a
+from sunpy.net import Fido
+
+#####################################################
+# Importing sunpy_soar registers the client with sunpy
+import sunpy_soar  # NOQA: F401
+
+#####################################################
+# We shall start with constructing a search query.
+
+instrument = a.Instrument("EUI")
+time = a.Time("2021-02-01", "2021-02-02")
+level = a.Level(1)
+product = a.soar.Product("EUI-FSI174-IMAGE")
+
+#####################################################
+# Now do the search.
+
+result = Fido.search(instrument & time & level & product)
+result
+
+#####################################################
+# Finally we can download the data.
+#
+# For this example, we will comment out the download part
+# as we want to avoid downloading data in the documentation build
+
+# files = Fido.fetch(result)
+# print(files)

examples/search_attrs.py

@@ -0,0 +1,44 @@
+"""
+===========================
+Available search attributes
+===========================
+
+This example demonstrates the available search attributes
+for SOAR currently supported by ``sunpy-soar``.
+"""
+
+import sunpy.net.attrs as a
+
+#####################################################
+# Importing sunpy_soar registers the client with sunpy
+import sunpy_soar  # NOQA: F401
+
+#####################################################
+# The easiest way to access search attributes is using
+# the attribute registry provided by `sunpy.net.attrs`.
+#
+# When constructing a search for SOAR ``a.Time`` must be provided.
+# Other search attributes can be used too - ``sunpy-soar`` recognizes the following:
+#
+# The third ``near`` argument to ``a.Time`` is not currently supported.
+# You will have to manually filter the results if you want to find the one closest to a given time.
+#
+# For instrument the following are supported:
+#
+# - "EPD": "Energetic Particle Detector"
+# - "EUI": "Extreme UV Imager"
+# - "MAG": "Magnetometer"
+# - "METIS": "Metis: Visible light and ultraviolet coronagraph"
+# - "PHI": "Polarimetric and Helioseismic Imager"
+# - "RPW": "Radio and Plasma Wave instrument"
+# - "SOLOHI": "Solar Orbiter Heliospheric Imager"
+# - "SPICE": "SPectral Investigation of the Coronal Environment"
+# - "STIX": "Spectrometer Telescope for Imaging X-rays"
+# - "SWA": "Solar Wind Analyser"
+#
+# For level the following are supported:
+# L0, L1, L2, L3, LL01, LL02, LL03
+#
+# For product:
+
+a.soar.Product

pyproject.toml

@@ -30,10 +30,13 @@ tests = [
   "sunpy[map,net]>=5.0",
 ]
 docs = [
-  "sphinx",
+  "matplotlib",
   "sphinx-automodapi",
   "sphinx-changelog",
   "sphinx-copybutton",
+  "sphinx-gallery",
+  "sphinx",
+  "sphinxext-opengraph",
   "sunpy-sphinx-theme",
 ]