Merge pull request #13 from sunpy/docs

Passover

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/sunpy/package-template",
-  "commit": "31e62add7400477edda83fa5ac399a5df0b86c89",
+  "commit": "49aadf8c3ce076e4c42edf6e8079855dd8a42aa4",
   "checkout": null,
   "context": {
     "cookiecutter": {
@@ -11,7 +11,7 @@
       "author_email": "sunpy@googlegroups.com",
       "project_url": "https://sunpy.org",
       "license": "GNU GPL v3+",
-      "minimum_python_version": "3.9",
+      "minimum_python_version": "3.10",
       "use_compiled_extensions": "n",
       "enable_dynamic_dev_versions": "y",
       "include_example_code": "n",

.github/workflows/ci.yml

@@ -68,6 +68,9 @@ jobs:
       submodules: false
       pytest: false
       toxdeps: tox-pypi-filter
+      libraries: |
+        apt:
+          - graphviz
       envs: |
         - linux: build_docs
 

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 repos:
     # This should be before any formatting hooks like isort
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.2.1"
+    rev: "v0.2.2"
     hooks:
       - id: ruff
         args: ["--fix"]

.ruff.toml

@@ -5,6 +5,7 @@ exclude = [
   "__pycache__",
   "build",
   "sunkit-magex/version.py",
+  "examples/testing/",
 ]
 
 [lint]
@@ -15,30 +16,19 @@ extend-ignore = [
   # pytest (PT)
   "PT001", # Always use pytest.fixture()
   "PT004", # Fixtures which don't return anything should have leading _
-  "PT007", # Parametrize should be lists of tuples  # TODO! fix
-  "PT011", # Too broad exception assert             # TODO! fix
   "PT023", # Always use () on pytest decorators
-
-  # pfsspy
-  # TODO: Fix these
-  "E741",
-  "F811",
 ]
 
-[lint.flake8-tidy-imports]
-[lint.flake8-tidy-imports.banned-api]
-"warnings.warn".msg = "Use sunpy specific warning helpers warn_* from sunpy.utils.exceptions"
-
 [lint.per-file-ignores]
 # Part of configuration, not a package.
 "setup.py" = ["INP001"]
 "conftest.py" = ["INP001"]
-# Implicit-namespace-package. The examples are not a package.
-"docs/*.py" = ["INP001"]
+"docs/*.py" = [
+  "INP001",  # Implicit-namespace-package. The examples are not a package.
+  "E402",  # Module imports not at top of file
+]
 "__init__.py" = ["E402", "F401", "F403"]
 "test_*.py" = ["B011", "D", "E402", "PGH001", "S101"]
-# Need to import clients to register them, but don't use them in file
-"sunkit-magex/net/__init__.py" = ["F811"]
 
 [lint.pydocstyle]
 convention = "numpy"

README.rst

@@ -1,43 +1,81 @@
-Potential field source surface modelling
-----------------------------------------
+``sunkit-magex``
+----------------
+
+``sunkit-magex`` is a Python software package that provides a set of tools for the modelling of magnetic field data.
+It is a SunPy affiliated package and is built on top of ``sunpy`` and ``astropy``.
+
+Currently it only supports the potential field source surface (PFSS) model, but we hope to expand it to include other models in the future.
+
+Installation
+============
+
+We recommended following the `installation guide <https://docs.sunpy.org/projects/sunkit-magex/en/latest/installing.html>`__ in the documentation.
+
+Usage
+=====
+
+If you are new to ``sunkit-magex``, the best place to start is the `example gallery <https://docs.sunpy.org/projects/sunkit-magex/en/latest/generated/gallery/index.html>`__.
+
+Changes
+=======
+
+See our `changelog <https://docs.sunpy.org/projects/sunkit-magex/en/latest/whatsnew/changelog.html>`__.
+
+Getting Help
+============
+
+For more information or to ask questions about ``sunkit-magex`` or any other SunPy Project package, please check out:
+
+-  `SunPy Chat`_
+-  `SunPy mailing list <https://groups.google.com/forum/#!forum/sunpy>`__
+-  `SunPy Community forum <https://community.openastronomy.org/c/sunpy/5>`__
+
+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>`__.
+
+.. _SunPy Chat: https://app.element.io/#/room/#sunpy:openastronomy.org
 
 License
 -------
 
-This project is Copyright (c) The SunPy Community and licensed under
-the terms of the GNU GPL v3+ license. This package is based upon
-the `Openastronomy packaging guide <https://github.com/OpenAstronomy/packaging-guide>`_
-which is licensed under the BSD 3-clause licence. See the licenses folder for
-more information.
+This project is Copyright (c) The SunPy Community and licensed under the terms of the GNU GPL v3+ license.
+This package is based upon the `Openastronomy packaging guide <https://github.com/OpenAstronomy/packaging-guide>`_ which is licensed under the BSD 3-clause license.
+See the licenses folder for more information.
 
 Contributing
 ------------
 
-We love contributions! sunkit-magex is open source,
-built on open source, and we'd love to have you hang out in our community.
-
-**Imposter syndrome disclaimer**: We want your help. No, really.
-
-There may be a little voice inside your head that is telling you that you're not
-ready to be an open source contributor; that your skills aren't nearly good
-enough to contribute. What could you possibly offer a project like this one?
-
-We assure you - the little voice in your head is wrong. If you can write code at
-all, you can contribute code to open source. Contributing to open source
-projects is a fantastic way to advance one's coding skills. Writing perfect code
-isn't the measure of a good developer (that would disqualify all of us!); it's
-trying to create something, making mistakes, and learning from those
-mistakes. That's how we all improve, and we are happy to help others learn.
-
-Being an open source contributor doesn't just mean writing code, either. You can
-help out by writing documentation, tests, or even giving feedback about the
-project (and yes - that includes giving feedback about the contribution
-process). Some of these contributions may be the most valuable to the project as
-a whole, because you're coming to the project with fresh eyes, so you can see
-the errors and assumptions that seasoned contributors have glossed over.
-
-Note: This disclaimer was originally written by
-`Adrienne Lowe <https://github.com/adriennefriend>`_ for a
-`PyCon talk <https://www.youtube.com/watch?v=6Uj746j9Heo>`_, and was adapted by
-sunkit-magex based on its use in the README file for the
-`MetPy project <https://github.com/Unidata/MetPy>`_.
+We love contributions! sunkit-magex is open source, built on open source, and we'd love to have you hang out in our community.
+
+**Imposter syndrome disclaimer**: We want your help.
+No, really.
+
+There may be a little voice inside your head that is telling you that you're not ready to be an open source contributor; that your skills aren't nearly good enough to contribute.
+What could you possibly offer a project like this one?
+
+We assure you - the little voice in your head is wrong.
+If you can write code at all, you can contribute code to open source.
+Contributing to open source projects is a fantastic way to advance one's coding skills.
+Writing perfect code isn't the measure of a good developer (that would disqualify all of us!); it's trying to create something, making mistakes, and learning from those mistakes.
+That's how we all improve, and we are happy to help others learn.
+
+Being an open source contributor doesn't just mean writing code, either.
+You can help out by writing documentation, tests, or even giving feedback about the project (and yes - that includes giving feedback about the contribution process).
+Some of these contributions may be the most valuable to the project as a whole, because you're coming to the project with fresh eyes, so you can see the errors and assumptions that seasoned contributors have glossed over.
+
+Note: This disclaimer was originally written by `Adrienne Lowe <https://github.com/adriennefriend>`_ for a `PyCon talk <https://www.youtube.com/watch?v=6Uj746j9Heo>`_, and was adapted for sunkit-magex based on its use in the README file for the `MetPy project <https://github.com/Unidata/MetPy>`_.

docs/conf.py

@@ -10,8 +10,8 @@
 
 # The full version, including alpha/beta/rc tags
 from sunkit_magex import __version__
-release = __version__
 
+release = __version__
 project = "sunkit-magex"
 copyright = "2024, The SunPy Community"
 author = "The SunPy Community"
@@ -51,6 +51,9 @@
 # The master toctree document.
 master_doc = "index"
 
+# Treat everything in single ` as a Python reference.
+default_role = 'py:obj'
+
 # -- Options for intersphinx extension ---------------------------------------
 
 intersphinx_mapping = {
@@ -69,23 +72,35 @@
 
 # -- Sphinx Gallery ----------------------------------------------------------
 
+from sunpy_sphinx_theme import PNG_ICON  # noqa
 from sphinx_gallery.sorting import ExplicitOrder  # noqa
 
 sphinx_gallery_conf = {
-    "ignore_pattern": ".*helpers.py",
-    "examples_dirs": "../examples",
+    "abort_on_example_error": False,
+    "backreferences_dir": os.path.join("generated", "modules"),
+    "default_thumb_file": PNG_ICON,
+    "examples_dirs": os.path.join("..", "examples"),
+    "filename_pattern": '^((?!skip_).)*$',
     "gallery_dirs": os.path.join("generated", "gallery"),
-    "subsection_order": ExplicitOrder(["../examples/using_pfsspy",
-                                       "../examples/finding_data",
-                                       "../examples/utils",
-                                       "../examples/pfsspy_info",
-                                       "../examples/testing"]),
-    "reference_url": {"sphinx_gallery": None}
+    "ignore_pattern": "helpers.py",
+    "matplotlib_animations": True,
+    "only_warn_on_example_error": True,
+    "plot_gallery": True,
+    "remove_config_comments": True,
+    "subsection_order": ExplicitOrder([
+        "../examples/using_pfsspy",
+        "../examples/finding_data",
+        "../examples/utils",
+        "../examples/internals",
+        "../examples/testing"
+    ]),
 }
 
 # -- Other options ----------------------------------------------------------
-default_role = 'py:obj'
 
+# JSOC email OS ENV
+# See https://github.com/sunpy/sunpy/wiki/Home:-JSOC
 os.environ["JSOC_EMAIL"] = 'jsoc@sunpy.org'
 
 nitpicky = True
+numfig = True

docs/index.rst

@@ -1,5 +1,6 @@
+**************************
 sunkit-magex Documentation
---------------------------
+**************************
 
 This is the documentation for sunkit-magex.
 
@@ -9,7 +10,7 @@ This is the documentation for sunkit-magex.
 
    installing
    generated/gallery/index
-   pfsspy
+   reference/index
    performance
-   numerical_method
+   numerical_methods_pfss/index.rst
    synoptic_fits

docs/installing.rst

@@ -1,15 +1,17 @@
+**********
 Installing
-----------
-sunkit_magex can be installed from PyPI using
+**********
 
-.. code::
+``sunkit_magex`` can be installed from PyPI using
+
+.. code:: shell
 
     pip install sunkit-magex
 
-This will install sunkit_magex and all of its dependencies. In addition to the core
-dependencies, there are two optional dependencies (numba, streamtracer) that
-improve code performance. These can be installed with
+This will install sunkit_magex and all of its dependencies.
+In addition to the core dependencies, there are two optional dependencies (numba, streamtracer) that can improve code performance.
+These can be installed with
 
-.. code::
+.. code:: shell
 
     pip install sunkit-magex[performance]