Merge pull request #7365 from meeseeksmachine/auto-backport-of-pr-732…

…5-on-5.1 Backport PR #7325 on branch 5.1 (Address review comments from the pyopensci reviewers)
sunpy · Jan 5, 2024 · 41d22d5 · 41d22d5
2 parents 68dea9e + 2647af3
commit 41d22d5
Show file tree

Hide file tree

Showing 10 changed files with 161 additions and 78 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -174,7 +174,7 @@ jobs:
     uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish.yml@main
     with:
       sdist: false
-      test_extras: 'all,tests'
+      test_extras: 'tests'
       test_command: 'pytest -p no:warnings --doctest-rst -m "not mpl_image_compare" --pyargs sunpy'
       submodules: false
       targets: |
@@ -189,7 +189,7 @@ jobs:
     uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish_pure_python.yml@main
     with:
       python-version: "3.10"
-      test_extras: 'all,tests'
+      test_extras: 'tests'
       test_command: 'pytest -p no:warnings --doctest-rst -m "not mpl_image_compare" --pyargs sunpy'
       submodules: false
       env: |

diff --git a/README.rst b/README.rst
@@ -2,93 +2,161 @@
 ``sunpy``
 *********
 
-|Latest Version| |DOI| |repostatus| |python|
-|ci| |codecov| |Docs|
-|matrix|
-|Powered by NumFOCUS|
-
-.. |Latest Version| image:: https://img.shields.io/pypi/v/sunpy.svg
-   :target: https://pypi.python.org/pypi/sunpy/
-.. |DOI| image:: https://zenodo.org/badge/2165383.svg
-   :target: https://zenodo.org/badge/latestdoi/2165383
-.. |matrix| image:: https://img.shields.io/matrix/sunpy:openastronomy.org.svg?colorB=%23FE7900&label=Chat&logo=matrix&server_fqdn=matrix.org
-   :target: https://app.element.io/#/room/#sunpy:openastronomy.org
-.. |codecov| image:: https://codecov.io/gh/sunpy/sunpy/branch/main/graph/badge.svg
-   :target: https://codecov.io/gh/sunpy/sunpy
-.. |Powered by NumFOCUS| image:: https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat&colorA=E1523D&colorB=007D8A
-   :target: https://numfocus.org
-.. |CI| image:: https://github.com/sunpy/sunpy/actions/workflows/ci.yml/badge.svg?branch=main
-   :target: https://github.com/sunpy/sunpy/actions/workflows/ci.yml
-.. |Docs| image:: https://readthedocs.org/projects/sunpy/badge/?version=stable
-   :target: https://docs.sunpy.org/en/stable/?badge=stable
-   :alt: Documentation Status
-.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg
-   :alt: Project Status: Active – The project has reached a stable, usable state and is being actively developed.
-   :target: https://www.repostatus.org/#active
-.. |python| image:: https://img.shields.io/pypi/pyversions/sunpy
-   :alt: PyPI - Python Version
+.. raw:: html
+
+    <img
+    src="https://raw.githubusercontent.com/sunpy/sunpy-logo/master/sunpy_logo_landscape.svg"
+    alt="SunPy Logo"
+    align="center"
+    width="200px" />
+    <table>
+    <thead>
+        <tr>
+        <th> Release </th>
+        <th> Development </th>
+        <th> Community </th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+        <td>
+            <a href="https://pypi.python.org/pypi/sunpy/"
+            ><img src="https://img.shields.io/pypi/v/sunpy.svg" alt="Latest PyPi Version"
+            /></a>
+        </td>
+        <td>
+            <a href="https://pypi.python.org/pypi/sunpy/"
+            ><img src="https://img.shields.io/pypi/pyversions/sunpy" alt="Python Versions"
+            /></a>
+        </td>
+        <td>
+            <a href="https://app.element.io/#/room/#sunpy:openastronomy.org"
+            ><img
+                src="https://img.shields.io/matrix/sunpy:openastronomy.org.svg?colorB=%23FE7900&label=Chat&logo=matrix&server_fqdn=matrix.org"
+                alt="Matrix Chat Room"
+            /></a>
+        </td>
+        </tr>
+        <tr>
+        <td>
+            <a href="https://anaconda.org/conda-forge/sunpy"
+            ><img src="https://anaconda.org/conda-forge/sunpy/badges/version.svg" alt="Latest Conda Version"
+            /></a>
+        </td>
+        <td>
+            <a href="https://www.repostatus.org/#active"
+            ><img
+                src="https://www.repostatus.org/badges/latest/active.svg"
+                alt="Project Status: Active - The project has reached a stable, usable state and is being actively developed."
+            /></a>
+        </td>
+        <td>
+            <a href="https://community.openastronomy.org/"
+            ><img
+                src="https://cdck-file-uploads-global.s3.dualstack.us-west-2.amazonaws.com/try2/original/1X/5e1e3b3cada2d7fbae4734d4bc53999933d71c95.svg"
+                height="20px"
+                alt="OpenAstronomy Discourse community"
+            /></a>
+        </td>
+        </tr>
+        <tr>
+        <td>
+            <a href="https://zenodo.org/badge/latestdoi/2165383"
+            ><img src="https://zenodo.org/badge/2165383.svg" alt="Zenodo - Latest DOI"
+            /></a>
+        </td>
+        <td>
+            <a href="https://github.com/sunpy/sunpy/actions/workflows/ci.yml"
+            ><img
+                src="https://github.com/sunpy/sunpy/actions/workflows/ci.yml/badge.svg?branch=main"
+                alt="Continuous Integration Status"
+            /></a>
+        </td>
+        <td>
+            <a href="https://groups.google.com/g/sunpy"
+            ><img
+                src="https://fonts.gstatic.com/s/i/productlogos/groups/v9/web-48dp/logo_groups_color_1x_web_48dp.png"
+                height="20px"
+                alt="Google Groups Mailing List"
+            /></a>
+        </td>
+        </tr>
+        <tr>
+        <td>
+            <a href="https://docs.sunpy.org/"
+            ><img src="https://readthedocs.org/projects/sunpy/badge/?version=stable" alt="sunpy Stable Documentation"
+            /></a>
+        </td>
+        <td>
+            <a href="https://codecov.io/gh/sunpy/sunpy"
+            ><img src="https://codecov.io/gh/sunpy/sunpy/branch/main/graph/badge.svg" alt="CodeCov Code Coverage"
+            /></a>
+        </td>
+        <td>
+            <a href="https://numfocus.org"
+            ><img
+                src="https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat&colorA=E1523D&colorB=007D8A"
+                alt="Powered by NumFOCUS"
+            /></a>
+        </td>
+        </tr>
+    </tbody>
+    </table>
+    <br />
 
 ``sunpy`` is a Python software package that provides fundamental tools for accessing, loading and interacting with solar physics data in Python.
-It is the core library of the `SunPy Project <https://sunpy.org/>`__.
-
-For some examples of using ``sunpy`` see our `gallery <https://docs.sunpy.org/en/stable/generated/gallery/index.html>`__.
-To see the latest changes in ``sunpy`` see our `changelog <https://docs.sunpy.org/en/stable/whatsnew/changelog.html>`__.
+It includes an interface for searching and downloading data from multiple data providers, data containers for image and time series data, commonly used solar coordinate frames and associated transformations, as well as other functionality needed for solar data analysis.
 
 Installation
 ============
 
-The recommended way to install ``sunpy`` is with `miniforge <https://github.com/conda-forge/miniforge#miniforge3>`__.
-To install ``sunpy`` once miniforge is installed run the following command:
-
-.. code:: bash
-
-    $ conda install sunpy
-
-For detailed installation instructions, see the `installation guide <https://docs.sunpy.org/en/stable/guide/installation.html>`__ in the ``sunpy`` docs.
+We recommended following the `installation guide <https://docs.sunpy.org/en/stable/guide/installation.html>`__ in the ``sunpy`` documentation.
+This will walk you through installing ``sunpy`` and all of its dependencies.
 
 Usage
 =====
 
-Here is a quick example of plotting an AIA image:
+If you are new to ``sunpy``, the best place to start is the `tutorial <https://docs.sunpy.org/en/stable/tutorial/index.html>`__.
+the `example gallery <https://docs.sunpy.org/en/stable/generated/gallery/index.html>`__ also includes a collection of shorter and more specific examples of using ``sunpy``.
 
-.. code:: python
+Changes
+=======
 
-   >>> import sunpy.map
-   >>> from sunpy.data.sample import AIA_171_IMAGE
-   >>>
-   >>> import matplotlib.pyplot as plt
-   >>>
-   >>> aia = sunpy.map.Map(AIA_171_IMAGE)
-   >>>
-   >>> aia.plot()
-   >>>
-   >>> plt.show()
+See our `changelog <https://docs.sunpy.org/en/stable/whatsnew/changelog.html>`__. for the latest changes in ``sunpy``.
 
 Getting Help
 ============
 
-For more information or to ask questions about ``sunpy`` or any other SunPy library, check out:
+For more information or to ask questions about ``sunpy`` or any other SunPy Project package, please check out:
 
 -  `sunpy documentation <https://docs.sunpy.org/en/stable/>`__
+-  `SunPy Affiliated Packages <https://sunpy.org/affiliated>`__
 -  `SunPy Chat`_
 -  `SunPy mailing list <https://groups.google.com/forum/#!forum/sunpy>`__
 -  `SunPy Community forum <https://community.openastronomy.org/c/sunpy/5>`__
 
 Acknowledging or Citing ``sunpy``
 =================================
 
-If you use ``sunpy`` in your scientific work, we would appreciate your `citing it in your publications <https://sunpy.org/about#acknowledging-or-citing-sunpy>`__.
+If you use ``sunpy`` in your scientific work, we would appreciate your `citing it in your publications <https://docs.sunpy.org/en/stable/citation.html>`__.
 The continued growth and development of ``sunpy`` is dependent on the community being aware of ``sunpy``.
 
 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.
+The SunPy Project is a community-driven open-source project that welcomes any and all contributions.
+Whether you are a developer, student, or user, you can help by contributing code, documentation, or community support.
+
+If you would like to get involved, the `Newcomers Guide`_ guide explains the many different ways to contribute to the SunPy Project and also shows how to get set up with a development workflow.
+
+Help is always welcome, so come and say hello by joining the `SunPy Chat`_ and look over the `Good First Issues list`_ for the ideal places to start.
+
+.. _Newcomers Guide: https://docs.sunpy.org/en/latest/dev_guide/contents/newcomers.html
+.. _Good First Issues list: https://github.com/sunpy/sunpy/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22Good+First+Issue%22
 
 Code of Conduct
 ===============
 
-When you are interacting with the SunPy community you are asked to follow our `Code of Conduct <https://sunpy.org/coc>`__.
+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
diff --git a/docs/about.rst → docs/citation.rst b/docs/about.rst → docs/citation.rst
diff --git a/docs/dev_guide/contents/tests.rst b/docs/dev_guide/contents/tests.rst
@@ -77,6 +77,13 @@ If a test errors, you can use ``pdb`` to create a debugging session at the momen
 
     $ pytest --pdb
 
+If you see mention of::
+
+    UserWarning: FigureCanvasAgg is non-interactive, and thus cannot be shown
+
+You will have to either export ``MPLBACKEND = agg`` as an environmental variable or pass it as a command line pre-argument to ``pytest``.
+This comes from the figure tests (see below).
+
 ``self_test``
 =============
 
@@ -104,7 +111,7 @@ If this is the case, you will see the following when you run the test suite::
     * sqlalchemy
     ...
     You do not have all the required dependencies installed to run the sunpy test suite.
-    If you want to run the sunpy tests install the 'tests' extra with `pip install "sunpy[all,tests]"`
+    If you want to run the sunpy tests install the 'tests' extra with `pip install "sunpy[tests]"`
 
 This does not mean sunpy is broken, but you will need to install the extra packages to ensure a "complete" installation of sunpy and run the entire test suite.
 It is quite likely that you will run into not having the tests dependencies installed.

diff --git a/docs/index.rst b/docs/index.rst
@@ -92,7 +92,7 @@ It includes an interface for searching and downloading data from multiple data p
     topic_guide/index
     reference/index
     whatsnew/index
-    about
+    citation
     reference/known_issues
     reference/stability
     dev_guide/index
diff --git a/docs/topic_guide/installation.rst b/docs/topic_guide/installation.rst
@@ -1,8 +1,13 @@
 .. _sunpy-topic-guide-installing:
 
-************
-Installation
-************
+*********************
+Advanced Installation
+*********************
+
+.. warning::
+
+    This page has advanced instructions for installing ``sunpy``.
+    If you are new to Python or ``sunpy``, please read the :ref:`installation instructions <sunpy-tutorial-installing>` first.
 
 The SunPy Project `maintains a range of affiliated packages <https://sunpy.org/project/affiliated>`__ that leverage the wider ecosystem of scientific Python packages for solar physics.
 This page focuses on how to install the ``sunpy`` core package, but these instructions should apply to most of the affiliated packages as well.
@@ -36,12 +41,17 @@ Once the environment active, to acquire a full ``sunpy`` installation:
 
     $ pip install "sunpy[all]"
 
-.. note::
 
-    We strive to provide binary wheels for all of our packages.
-    If you are using a Python version or operating system that is missing a binary wheel.
-    ``pip`` will try to compile the package from source and this is likely to fail without a C compiler (e.g., ``gcc`` or ``clang``).
-    Getting the compiler either from your system package manager or XCode should address this.
+.. warning::
+
+    If you get a ``PermissionError`` this means that you do not have the required administrative access to install new packages to your Python installation.
+    Do **not** install ``sunpy`` or other Python packages using ``sudo``.
+    This error implies you have an incorrectly configured virtual environment or it is not activated.
+
+We strive to provide binary wheels for all of our packages.
+If you are using a Python version or operating system that is missing a binary wheel,
+``pip`` will try to compile the package from source and this is likely to fail without a C compiler (e.g., ``gcc`` or ``clang``).
+Getting the compiler either from your system package manager or XCode (if you are using macOS) should address this.
 
 If you have a reason to want a more minimal installation, you can install sunpy with no optional dependencies, however this means a lot of submodules will not import:
 
@@ -57,12 +67,6 @@ It is possible to select which "extra" dependencies you want to install, if you
 
 The available options are: ``[asdf]``, ``[dask]``, ``[database]``, ``[image]``, ``[jpeg2000]``, ``[map]``, ``[net]``, ``[timeseries]``, ``[visualization]``.
 
-.. note::
-
-    If you get a ``PermissionError`` this means that you do not have the required administrative access to install new packages to your Python installation.
-    Do **not** install ``sunpy`` or other Python packages using ``sudo``.
-    This error implies you have an incorrectly configured virtual environment or it is not activated.
-
 Updating a pip package
 ----------------------
 

diff --git a/docs/tutorial/installation.rst b/docs/tutorial/installation.rst
@@ -5,15 +5,16 @@ Installation
 ************
 
 This is the first chapter in the sunpy tutorial, and by the end of it you should have a working installation of Python and ``sunpy``.
-For more info on different ways to install ``sunpy`` beyond the recommended way below, see :ref:`sunpy-topic-guide-installing`.
+For further information and alternative methods for installing ``sunpy`` beyond the recommended approach outlined below, refer to :ref:`sunpy-topic-guide-installing`.
 
 Installing Python
 =================
 
 There are many ways to install Python, but even if you have Python installed somewhere on your computer we recommend following these instructions anyway.
 That's because we will create a new Python environment.
 As well as containing a Python installation, this environment provides an isolated place to install Python packages (like ``sunpy``) without affecting any other current Python installation.
-If you already have Python and either ``conda`` or ``pip`` working you can skip the next section.
+If you already have Python and ``conda`` working you can skip the next section.
+However, if you are using Anaconda, we recommend you still install miniforge as described below.
 
 Installing miniforge
 --------------------
@@ -57,7 +58,7 @@ Then select your platform to install miniforge:
 
         .. code-block:: console
 
-           bash Miniforge3-$(uname)-$(uname -m).sh
+            bash Miniforge3-$(uname)-$(uname -m).sh
 
         Once the installer has completed, close and reopen your terminal.
 
@@ -83,6 +84,7 @@ Now we will create and activate a new virtual environment to install ``sunpy`` i
     $ conda create --name sunpy
     # Only run the following two lines
     # if you have NOT installed miniforge or added conda-forge to your channels
+    # Do not run these lines if you are using Anaconda
     $ conda config --add channels conda-forge
     $ conda config --set channel_priority strict
     $ conda activate sunpy

diff --git a/pyproject.toml b/pyproject.toml
@@ -14,7 +14,7 @@ write_to = "sunpy/_version.py"
 # Until we have h5py binaries we can't test wheels on Python 3.11
 [tool.cibuildwheel]
 test-command = "pytest -p no:warnings --doctest-rst -m 'not mpl_image_compare' --pyargs sunpy"
-test-extras = ["all,tests"]
+test-extras = ["tests"]
 
 [ tool.gilesbot ]
   [ tool.gilesbot.circleci_artifacts ]

diff --git a/setup.cfg b/setup.cfg
@@ -98,6 +98,7 @@ all =
   %(timeseries)s
   %(visualization)s
 tests =
+  %(all)s
   hvpy>=1.0.1
   hypothesis>=6.0.0  # Included in pytest-astropy. 6.0 is the first version to support disabling function-scoped fixture warning
   jplephem  # For some coordinates tests
@@ -110,6 +111,7 @@ tests =
   pytest>=6.0
   %(spice)s
 docs =
+  %(all)s
   hvpy>=1.0.1
   packaging
   ruamel.yaml
@@ -157,7 +159,7 @@ testpaths = "sunpy" "docs"
 norecursedirs = ".tox" "build" "docs[\/]_build" "docs[\/]generated" "*.egg-info" "examples" "sunpy[/\]_dev" ".jupyter" ".history" "tools" "sunpy[\/]extern" "benchmarks"
 doctest_plus = enabled
 doctest_optionflags = NORMALIZE_WHITESPACE FLOAT_CMP ELLIPSIS
-addopts = --dist no --arraydiff --doctest-rst --doctest-ignore-import-errors -p no:unraisableexception -p no:threadexception
+addopts = --dist no --arraydiff --doctest-rst --doctest-ignore-import-errors -p no:unraisableexception -p no:threadexception -m "not mpl_image_compare"
 asdf_schema_tests_enabled = true
 asdf_schema_root = sunpy/io/special/asdf/resources/
 mpl-results-path = figure_test_images

diff --git a/sunpy/tests/self_test.py b/sunpy/tests/self_test.py
@@ -58,7 +58,7 @@ def self_test(*, package=None, online=False, online_only=False, figure_only=Fals
         print(list(test_missing.keys()))
         print()
         print("If are using conda, you will want to run conda install <package name>")
-        print('Otherwise you will want run pip install "sunpy[all,tests]"')
+        print('Otherwise you will want run pip install "sunpy[tests]"')
         print()
         return 1
     print()