Skip to content

Commit 11334f2

Browse files
hayeslanabobalis
hayesla
and
nabobalis
authored
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 <[email protected]>
1 parent 6841a1b commit 11334f2

File tree

11 files changed

+145
-86
lines changed

11 files changed

+145
-86
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,17 @@ jobs:
9696
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
9797

9898
publish_pure:
99+
# publish_pure will only publish if tagged ^v.*
100+
if: |
101+
(
102+
github.event_name != 'pull_request' && (
103+
github.ref_name != 'main' ||
104+
github.event_name == 'workflow_dispatch'
105+
)
106+
) || (
107+
github.event_name == 'pull_request' &&
108+
contains(github.event.pull_request.labels.*.name, 'Run publish')
109+
)
99110
needs: [test, docs]
100111
uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish_pure_python.yml@main
101112
with:

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -238,12 +238,14 @@ $RECYCLE.BIN/
238238
# Windows shortcuts
239239
*.lnk
240240

241-
### Extra Python Items and SunPy Specific
241+
### Extra Python Items and Package Specific
242242
docs/whatsnew/latest_changelog.txt
243243
examples/**/*.csv
244244
figure_test_images*
245245
tags
246246
baseline
247+
docs/generated/
248+
docs/sg_execution_times.rst
247249

248250
# Release script
249251
.github_cache

‎.ruff.toml‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -63,18 +63,16 @@ lint.select = [
6363
"YTT",
6464
]
6565
lint.extend-ignore = [
66-
# TODO: Fix in future
67-
"E501", # Line too long
68-
"E741", # Ambiguous variable name
69-
"FBT002", # Bool arg
7066
"COM812", # May cause conflicts when used with the formatter
7167
"ISC001", # May cause conflicts when used with the formatter
7268
]
7369

7470
[lint.per-file-ignores]
7571
"examples/*.py" = [
76-
"INP001", # examples is part of an implicit namespace package
77-
"T201", # We need print in our examples
72+
"INP001", # Implicit namespace package
73+
"T201", # Use print
74+
"B018", # Not print but display
75+
"ERA001", # Commented out code
7876
]
7977
"docs/conf.py" = [
8078
"INP001", # conf.py is part of an implicit namespace package

‎docs/api.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Reference/API
2+
=============
3+
4+
.. automodapi:: sunpy_soar

‎docs/coc.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Code of Conduct
2+
===============
3+
4+
When you are interacting with the SunPy community you are asked to follow our `Code of Conduct <https://sunpy.org/coc>`__.

‎docs/conf.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
import datetime
99
from pathlib import Path
1010

11+
from sunpy_sphinx_theme import PNG_ICON
12+
1113
from sunpy_soar import __version__
1214

1315
project = "sunpy-soar"
@@ -18,6 +20,8 @@
1820

1921
# -- General configuration ---------------------------------------------------
2022
extensions = [
23+
"sphinx_gallery.gen_gallery",
24+
"matplotlib.sphinxext.plot_directive",
2125
"sphinx_automodapi.automodapi",
2226
"sphinx_automodapi.smart_resolver",
2327
"sphinx_changelog",
@@ -90,3 +94,19 @@
9094
dtype, target = line.split(None, 1)
9195
target = target.strip()
9296
nitpick_ignore.append((dtype, target))
97+
98+
# -- Options for the Sphinx gallery -------------------------------------------
99+
sphinx_gallery_conf = {
100+
"backreferences_dir": Path("generated") / "modules",
101+
"filename_pattern": "^((?!skip_).)*$",
102+
"examples_dirs": Path("..") / "examples",
103+
"gallery_dirs": Path("generated") / "gallery",
104+
"matplotlib_animations": True,
105+
# Comes from the theme.
106+
"default_thumb_file": PNG_ICON,
107+
"abort_on_example_error": False,
108+
"plot_gallery": "True",
109+
"remove_config_comments": True,
110+
"doc_module": ("sunpy-soar"),
111+
"only_warn_on_example_error": True,
112+
}

‎docs/index.rst‎

Lines changed: 8 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,11 @@
44

55
A sunpy Fido plugin for accessing data in the Solar Orbiter Archive (SOAR).
66

7-
.. toctree::
8-
:maxdepth: 1
9-
10-
changelog
11-
127
Installation
138
============
149

15-
``sunpy-soar`` requires ``python >= 3.9`` and ``sunpy >= 5.0``.
16-
Currently it can only be installed from PyPI using:
10+
``sunpy-soar`` requires ``python >= 3.10`` and ``sunpy >= 5.0``.
11+
Currently it can be installed from PyPI using:
1712

1813
.. code-block:: bash
1914
@@ -25,69 +20,6 @@ or conda using
2520
2621
conda install -c conda-forge sunpy_soar
2722
28-
Example
29-
=======
30-
31-
The code below gives an example of how to search and download Solar Orbiter data using ``sunpy.net.Fido``:
32-
33-
.. code-block:: python
34-
35-
# Importing sunpy_soar registers the client with sunpy
36-
>>> import sunpy_soar
37-
>>> from sunpy.net import Fido
38-
>>> import sunpy.net.attrs as a
39-
40-
# Create search attributes
41-
>>> instrument = a.Instrument('EUI')
42-
>>> time = a.Time('2021-02-01', '2021-02-02')
43-
>>> level = a.Level(1)
44-
>>> product = a.soar.Product('EUI-FSI174-IMAGE')
45-
46-
# Do search
47-
>>> result = Fido.search(instrument & time & level & product)
48-
>>> print(result)
49-
Results from 1 Provider:
50-
<BLANKLINE>
51-
43 Results from the SOARClient:
52-
<BLANKLINE>
53-
Instrument Data product Level Start time End time Filesize SOOP Name
54-
Mbyte
55-
---------- ---------------- ----- ----------------------- ----------------------- -------- ---------
56-
EUI eui-fsi174-image L1 2021-02-01 00:45:12.228 2021-02-01 00:45:22.228 3.393 none
57-
EUI eui-fsi174-image L1 2021-02-01 01:15:12.232 2021-02-01 01:15:22.232 0.418 none
58-
EUI eui-fsi174-image L1 2021-02-01 01:45:12.237 2021-02-01 01:45:22.237 0.406 none
59-
EUI eui-fsi174-image L1 2021-02-01 02:15:12.238 2021-02-01 02:15:22.238 3.352 none
60-
EUI eui-fsi174-image L1 2021-02-01 02:45:12.241 2021-02-01 02:45:22.241 0.406 none
61-
EUI eui-fsi174-image L1 2021-02-01 03:15:12.244 2021-02-01 03:15:22.244 0.406 none
62-
... ... ... ... ... ... ...
63-
EUI eui-fsi174-image L1 2021-02-01 20:44:52.224 2021-02-01 20:45:02.224 0.409 none
64-
EUI eui-fsi174-image L1 2021-02-01 21:15:12.227 2021-02-01 21:15:22.227 3.387 none
65-
EUI eui-fsi174-image L1 2021-02-01 21:45:12.230 2021-02-01 21:45:22.230 0.412 none
66-
EUI eui-fsi174-image L1 2021-02-01 22:15:12.233 2021-02-01 22:15:22.233 0.415 none
67-
EUI eui-fsi174-image L1 2021-02-01 22:44:52.236 2021-02-01 22:45:02.236 0.423 none
68-
EUI eui-fsi174-image L1 2021-02-01 23:15:12.239 2021-02-01 23:15:22.239 3.459 none
69-
EUI eui-fsi174-image L1 2021-02-01 23:45:12.242 2021-02-01 23:45:22.242 0.415 none
70-
Length = 43 rows
71-
<BLANKLINE>
72-
<BLANKLINE>
73-
74-
# Download files
75-
>>> files = Fido.fetch(result) # doctest: +SKIP
76-
>>> print(files) # doctest: +SKIP
77-
78-
Available search attributes
79-
===========================
80-
81-
The easiest way to access search attributes is using ``import sunpy.net.attrs as a``.
82-
When constructing a search for SOAR ``a.Time`` must be provided.
83-
Other search attributes can be used too - ``sunpy-soar`` recognises the following:
84-
85-
- ``a.Instrument``
86-
- ``a.Level`` - one of ``L0, L1, L2, L3, LL01, LL02, LL03``
87-
- ``a.soar.Product``
88-
89-
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.
90-
9123
``sunpy-soar`` and the VSO
9224
==========================
9325

@@ -111,14 +43,12 @@ Contributing
11143
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>`__.
11244
This will walk you through getting set up for contributing.
11345

114-
Code of Conduct
115-
===============
116-
117-
When you are interacting with the SunPy community you are asked to follow our `Code of Conduct <https://sunpy.org/coc>`__.
118-
11946
.. _SunPy Chat: https://app.element.io/#/room/#sunpy:openastronomy.org
12047

121-
Reference/API
122-
=============
48+
.. toctree::
49+
:hidden:
12350

124-
.. automodapi:: sunpy_soar
51+
generated/gallery/index
52+
api
53+
changelog
54+
coc

‎examples/README.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
***************
2+
Example Gallery
3+
***************
4+
5+
This gallery contains examples of how to use ``sunpy-soar``.
6+

‎examples/quick.py‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
"""
2+
============================================
3+
Quick overview of using sunpy-soar with Fido
4+
============================================
5+
6+
This example demonstrates how to search and download Solar Orbiter data using ``sunpy.net.Fido``.
7+
"""
8+
9+
import sunpy.net.attrs as a
10+
from sunpy.net import Fido
11+
12+
#####################################################
13+
# Importing sunpy_soar registers the client with sunpy
14+
import sunpy_soar # NOQA: F401
15+
16+
#####################################################
17+
# We shall start with constructing a search query.
18+
19+
instrument = a.Instrument("EUI")
20+
time = a.Time("2021-02-01", "2021-02-02")
21+
level = a.Level(1)
22+
product = a.soar.Product("EUI-FSI174-IMAGE")
23+
24+
#####################################################
25+
# Now do the search.
26+
27+
result = Fido.search(instrument & time & level & product)
28+
result
29+
30+
#####################################################
31+
# Finally we can download the data.
32+
#
33+
# For this example, we will comment out the download part
34+
# as we want to avoid downloading data in the documentation build
35+
36+
# files = Fido.fetch(result)
37+
# print(files)

‎examples/search_attrs.py‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
"""
2+
===========================
3+
Available search attributes
4+
===========================
5+
6+
This example demonstrates the available search attributes
7+
for SOAR currently supported by ``sunpy-soar``.
8+
"""
9+
10+
import sunpy.net.attrs as a
11+
12+
#####################################################
13+
# Importing sunpy_soar registers the client with sunpy
14+
import sunpy_soar # NOQA: F401
15+
16+
#####################################################
17+
# The easiest way to access search attributes is using
18+
# the attribute registry provided by `sunpy.net.attrs`.
19+
#
20+
# When constructing a search for SOAR ``a.Time`` must be provided.
21+
# Other search attributes can be used too - ``sunpy-soar`` recognizes the following:
22+
#
23+
# The third ``near`` argument to ``a.Time`` is not currently supported.
24+
# You will have to manually filter the results if you want to find the one closest to a given time.
25+
#
26+
# For instrument the following are supported:
27+
#
28+
# - "EPD": "Energetic Particle Detector"
29+
# - "EUI": "Extreme UV Imager"
30+
# - "MAG": "Magnetometer"
31+
# - "METIS": "Metis: Visible light and ultraviolet coronagraph"
32+
# - "PHI": "Polarimetric and Helioseismic Imager"
33+
# - "RPW": "Radio and Plasma Wave instrument"
34+
# - "SOLOHI": "Solar Orbiter Heliospheric Imager"
35+
# - "SPICE": "SPectral Investigation of the Coronal Environment"
36+
# - "STIX": "Spectrometer Telescope for Imaging X-rays"
37+
# - "SWA": "Solar Wind Analyser"
38+
#
39+
# For level the following are supported:
40+
# L0, L1, L2, L3, LL01, LL02, LL03
41+
#
42+
# For product:
43+
44+
a.soar.Product

0 commit comments

Comments
 (0)