Fixes to documentation theme and package infrastructure fixes (#286)

* I hear you like updates * reduce top level name space * Update fiasco/io/factory.py Co-authored-by: Will Barnes <will.t.barnes@gmail.com> * Update fiasco/util/exceptions.py Co-authored-by: Will Barnes <will.t.barnes@gmail.com> --------- Co-authored-by: Will Barnes <will.t.barnes@gmail.com>
wtbarnes · May 22, 2024 · 7dddd7e · 7dddd7e
1 parent 9ab2c61
commit 7dddd7e
Show file tree

Hide file tree

Showing 38 changed files with 314 additions and 278 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -10,64 +10,73 @@ on:
   pull_request:
   workflow_dispatch:
 
-
 jobs:
-  test:
+  core:
+    uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
+    with:
+      posargs: '--ascii-dbase-root ~/.chianti'
+      toxdeps: tox-pypi-filter
+      envs: |
+        - linux: py312
+      coverage: 'codecov'
+      cache-path: ~/.chianti
+      cache-key: chianti-${{ github.event.number }}
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  tests:
+    needs: [core]
     uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
     with:
       posargs: '--ascii-dbase-root ~/.chianti'
-      toxdeps: "'tox<4' tox-pypi-filter"
+      toxdeps: tox-pypi-filter
       envs: |
         - macos: py311
-        - windows: py311
-        - linux: py39
-        - linux: py310
-        - linux: py311
+        - windows: py310
       coverage: 'codecov'
       cache-path: ~/.chianti
       cache-key: chianti-${{ github.event.number }}
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
   test_full_database:
-    needs: [test]
+    needs: [tests]
     uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
     with:
       posargs: '--ascii-dbase-root ~/.chianti --include-all-files'
-      toxdeps: "'tox<4' tox-pypi-filter"
+      toxdeps: tox-pypi-filter
       envs: |
         - linux: py311
       cache-path: ~/.chianti
       cache-key: chianti-${{ github.event.number }}
+
   test_database_v7:
-    needs: [test]
+    needs: [tests]
     uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
     with:
       posargs: '--ascii-dbase-root ~/.chianti --ascii-dbase-url http://download.chiantidatabase.org/CHIANTI_v7.1.4_database.tar.gz --disable-file-hash --skip-version-check'
-      toxdeps: "'tox<4' tox-pypi-filter"
+      toxdeps: tox-pypi-filter
       envs: |
         - linux: py311
+
   test_database_v9:
-    needs: [test]
+    needs: [tests]
     uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
     with:
       posargs: '--ascii-dbase-root ~/.chianti --ascii-dbase-url http://download.chiantidatabase.org/CHIANTI_v9.0.1_database.tar.gz --disable-file-hash --skip-version-check'
-      toxdeps: "'tox<4' tox-pypi-filter"
+      toxdeps: tox-pypi-filter
       envs: |
         - linux: py311
-  precommit:
-    uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
-    with:
-      toxdeps: "'tox<4' tox-pypi-filter"
-      envs: |
-        - linux: pre-commit
+
   docs:
-    needs: [test]
+    needs: [tests]
     uses: OpenAstronomy/github-actions-workflows/.github/workflows/tox.yml@v1
     with:
-      toxdeps: "'tox<4' tox-pypi-filter"
+      toxdeps: tox-pypi-filter
       envs: |
-        - linux: build_docs
-          python-version: '3.11'
+        - linux: build_docs-gallery
+          python-version: '3.12'
+
   publish:
     # Build wheels when pushing to any branch except main
     # publish.yml will only publish if tagged ^v.*
@@ -81,12 +90,12 @@ jobs:
         github.event_name == 'pull_request' &&
         contains(github.event.pull_request.labels.*.name, 'Run publish')
       )
-    needs: [test,test_full_database]
+    needs: [tests,test_full_database]
     uses: OpenAstronomy/github-actions-workflows/.github/workflows/publish_pure_python.yml@main
     with:
       test_extras: 'dev'
       test_command: 'pytest -p no:warnings --doctest-rst --pyargs fiasco'
       submodules: false
-      python-version: '3.11'
+      python-version: '3.12'
     secrets:
       pypi_token: ${{ secrets.PYPI_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -155,3 +155,5 @@ htmlcov/
 # IDEs
 
 .idea
+.history
+.vscode
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,12 +1,12 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.1.5"
+    rev: "v0.4.4"
     hooks:
       - id: ruff
         args: ["--fix"]
 
   - repo: https://github.com/PyCQA/isort
-    rev: 5.12.0
+    rev: 5.13.2
     hooks:
     - id: isort
       name: isort
@@ -17,7 +17,7 @@ repos:
       - python
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.6.0
     hooks:
       - id: check-ast
       - id: check-case-conflict

diff --git a/docs/conf.py b/docs/conf.py
@@ -2,32 +2,30 @@
 # Configuration file for the Sphinx documentation builder.
 #
 import configparser
+import datetime
 import os
 import pathlib
 
+from sphinx_gallery.sorting import ExplicitOrder
+
 # This file does only contain a selection of the most common options. For a
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
 
 
 # -- Project information -----------------------------------------------------
-
 project = 'fiasco'
-copyright = '2022, Will Barnes'
+copyright = f'{datetime.datetime.now(datetime.UTC).year}, Will Barnes'
 author = 'Will Barnes'
-
 # The full version, including alpha/beta/rc tags
 from fiasco import __version__
 
 release = __version__
 is_development = '.dev' in __version__
 
 # -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
+    'sphinxcontrib.bibtex',
     'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
@@ -40,61 +38,54 @@
     'sphinx.ext.mathjax',
     'sphinx_automodapi.automodapi',
     'sphinx_automodapi.smart_resolver',
-    'sphinxcontrib.bibtex',
     'sphinx_design',
+    'sphinx_gallery.gen_gallery',
 ]
-
-# Add any paths that contain templates here, relative to this directory.
-# templates_path = ['_templates']
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
 source_suffix = '.rst'
-
-# The master toctree document.
 master_doc = 'index'
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents. Set to the "smart" one.
 default_role = 'obj'
-
-# Disable having a separate return type row
 napoleon_use_rtype = False
-
-# Disable google style docstrings
 napoleon_google_docstring = False
 
-# -- Options for intersphinx extension ---------------------------------------
+# Enable nitpicky mode, which forces links to be non-broken
+nitpicky = True
+# This is not used. See docs/nitpick-exceptions file for the actual listing.
+nitpick_ignore = []
+for line in open('nitpick-exceptions'):
+    if line.strip() == "" or line.startswith("#"):
+        continue
+    dtype, target = line.split(None, 1)
+    target = target.strip()
+    nitpick_ignore.append((dtype, target))
 
-# Example configuration for intersphinx: refer to the Python standard library.
+# -- Options for intersphinx extension ---------------------------------------
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/',
-               (None, 'http://data.astropy.org/intersphinx/python3.inv')),
-    'numpy': ('https://numpy.org/doc/stable/',
-              (None, 'http://data.astropy.org/intersphinx/numpy.inv')),
-    'scipy': ('https://docs.scipy.org/doc/scipy/reference/',
-              (None, 'http://data.astropy.org/intersphinx/scipy.inv')),
-    'matplotlib': ('https://matplotlib.org/',
-                   (None, 'http://data.astropy.org/intersphinx/matplotlib.inv')),
-    'astropy': ('https://docs.astropy.org/en/stable', None),
-    'sunpy': ('https://docs.sunpy.org/en/stable/', None),
-    'aiapy': ('https://aiapy.readthedocs.io/en/stable/', None),
+    "python": (
+        "https://docs.python.org/3/",
+        (None, "http://www.astropy.org/astropy-data/intersphinx/python3.inv"),
+    ),
+    "numpy": (
+        "https://numpy.org/doc/stable/",
+        (None, "http://www.astropy.org/astropy-data/intersphinx/numpy.inv"),
+    ),
+    "scipy": (
+        "https://docs.scipy.org/doc/scipy/reference/",
+        (None, "http://www.astropy.org/astropy-data/intersphinx/scipy.inv"),
+    ),
     'plasmapy': ('https://docs.plasmapy.org/en/stable', None),
+    'sunpy': ('https://docs.sunpy.org/en/stable/', None),
+    "aiapy": ("https://aiapy.readthedocs.io/en/stable/", None),
+    "asdf": ("https://asdf.readthedocs.io/en/stable/", None),
+    "astropy": ("https://docs.astropy.org/en/stable/", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "packaging": ("https://packaging.pypa.io/en/stable/", None),
 }
 
 # -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-
 html_theme = 'pydata_sphinx_theme'
 
-# -- Sphinx Book Theme Options -----------------------------------------------------
+# -- Sphinx Book Theme Options -----------------------------------------------
 html_theme_options = {
     "use_edit_page_button": True,
     "icon_links": [
@@ -114,9 +105,6 @@
             "icon": "fa-solid fa-wine-glass",
         }
     ],
-    #"secondary_sidebar_items": {
-    #    "index": []  # Remove secondary sidebar on landing page
-    #},
     "announcement": "fiasco currently only supports version 8 of the CHIANTI database.",
 }
 html_context = {
@@ -126,16 +114,15 @@
     "doc_path": "docs",
 }
 html_logo = '_static/fiasco-logo.png'
-
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
-
+# Set path for BibTeX file for all of our references
+bibtex_bibfiles = ['references.bib']
+# Sidebar removal
+html_sidebars = {
+    "quick_start*": [],
+    "how_to_guides*": [],
+}
 # Render inheritance diagrams in SVG
 graphviz_output_format = "svg"
-
 graphviz_dot_args = [
     '-Nfontsize=10',
     '-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif',
@@ -145,9 +132,7 @@
     '-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif'
 ]
 
-# Set path for BibTeX file for all of our references
-bibtex_bibfiles = ['references.bib']
-
+# -- Database on RTD -----------------------------------------------
 ON_RTD = os.environ.get('READTHEDOCS') == 'True'
 ON_GHA = os.environ.get('CI') == 'true'
 
@@ -173,17 +158,21 @@
         c.write(f)
 
 # -- Sphinx gallery -----------------------------------------------------------
-from sphinx_gallery.sorting import ExampleTitleSortKey, ExplicitOrder  # NOQA: E402
-
-extensions += ['sphinx_gallery.gen_gallery']
 sphinx_gallery_conf = {
+    'backreferences_dir': os.path.join('generated', 'modules'),
+    'filename_pattern': '^((?!skip_).)*$',
+    'examples_dirs': os.path.join('..', 'examples'),
     'subsection_order': ExplicitOrder([
         '../examples/user_guide/',
         '../examples/idl_comparisons/',
     ]),
-    'within_subsection_order': ExampleTitleSortKey,
-    'examples_dirs': '../examples',   # path to your example scripts
-    'gallery_dirs': 'generated/gallery',  # path to where to save gallery generated output
-    'filename_pattern': '^((?!skip_).)*$',
-    'default_thumb_file': '_static/fiasco-logo.png'
+    'within_subsection_order': 'ExampleTitleSortKey',
+    'gallery_dirs': os.path.join('generated', 'gallery'),
+    'matplotlib_animations': True,
+    "default_thumb_file": '_static/fiasco-logo.png',
+    'abort_on_example_error': False,
+    'plot_gallery': 'True',
+    'remove_config_comments': True,
+    'doc_module': ('fiasco',),
+    'only_warn_on_example_error': True,
 }
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,7 +1,8 @@
 fiasco Documentation
-=====================
+====================
 
 Welcome to the documentation for fiasco.
+
 fiasco provides a Python interface to the `CHIANTI atomic database`_.
 In addition to several high-level abstractions of the atomic data, fiasco also provides many common atomic physics calculations.
 The package takes its name from the Italian word *fiasco*, or flask, `the typical style of bottle <https://en.wikipedia.org/wiki/Fiasco_(bottle)>`_ used to serve the *Chianti Classico* wine.
@@ -47,13 +48,13 @@ In the same way, the `fiasco` package serves up the CHIANTI atomic database.
         Technical description of the inputs, outputs, and behavior of each component of fiasco
 
 .. toctree::
-  :maxdepth: 1
-  :hidden:
-
-  quick_start
-  generated/gallery/index
-  how_to_guides
-  topic_guides/index
-  reference/index
+    :maxdepth: 1
+    :hidden:
+
+    quick_start
+    generated/gallery/index
+    how_to_guides
+    topic_guides/index
+    reference/index
 
 .. _CHIANTI atomic database: http://www.chiantidatabase.org/
-Original file line number
+Diff line change
@@ Expand Up / @@ -155,3 +155,5 @@ htmlcov/ @@
     # IDEs
     .idea
+    .history
+    .vscode