Migrate Docs to Sphinx-Design, Remove NPS, Update Workflows (#109)

fsoubelet · Jul 22, 2024 · 9a9daf2 · 9a9daf2
1 parent 078c533
commit 9a9daf2
Show file tree

Hide file tree

Showing 21 changed files with 269 additions and 241 deletions.
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
@@ -13,23 +13,23 @@ on:  # Runs on all push events to master branch and any push related to a pull r
 
 jobs:
   coverage:
-    name: ${{ matrix.os }} / ${{ matrix.python-version }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:  # only lowest supported python on ubuntu-latest
-        os: [ubuntu-latest]
-        python-version: [3.11]
+    runs-on: ubuntu-latest
+    env:
+        python-version: 3.12
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python ${{ env.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ matrix.python-version }}
-          cache: pip
+          python-version: ${{ env.python-version }}
+          cache: 'pip'
           cache-dependency-path: '**/pyproject.toml'
 
+      - name: Upgrade pip, setuptools and wheel
+        run: python -m pip install --upgrade pip setuptools wheel
+
       - name: Install package with test dependencies
         run: python -m pip install ".[test]"
 
@@ -40,6 +40,6 @@ jobs:
         run: make alltests
 
       - name: Upload Coverage to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
diff --git a/.github/workflows/cron.yml b/.github/workflows/cron.yml
@@ -15,17 +15,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-22.04, macos-latest, windows-latest]
-        python-version: [3.8, 3.9, "3.10", 3.11, 3.12, 3.x]  # crons should always run latest python hence 3.x
-        # exclude:
-          # - os: windows-latest  # scipy deps issues
-          #   python-version: "3.10"
-          # - os: windows-latest
-          #   python-version: "3.x"
-          # - os: macos-latest  # scipy deps issues
-          #   python-version: "3.10"
-          # - os: macos-latest
-          #   python-version: "3.x"
+        os: [ubuntu-22.04, ubuntu-24.04, macos-latest, windows-latest]
+        python-version: ["3.10", 3.11, 3.12, 3.x]  # crons should always run latest python hence 3.x
       fail-fast: false
 
     steps:
@@ -35,9 +26,12 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: pip
+          cache: 'pip'
           cache-dependency-path: '**/pyproject.toml'
 
+      - name: Upgrade pip, setuptools and wheel
+        run: python -m pip install --upgrade pip setuptools wheel
+
       - name: Install package with test dependencies
         run: python -m pip install ".[test]"
 

diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
@@ -21,29 +21,29 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
+        uses: docker/setup-qemu-action@v3
 
       - name: Set up Docker Buildx
         id: buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v3
 
       - name: Cache Docker layers
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: /tmp/.buildx-cache
           key: ${{ runner.os }}-buildx-${{ github.sha }}
           restore-keys: |
             ${{ runner.os }}-buildx-
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_ID }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build and push image
         id: docker_build
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v6
         with:
           context: ./
           file: ./docker/Dockerfile

diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -13,12 +13,9 @@ on:  # Runs on any push event in a PR or any push event to master
 
 jobs:
   documentation:
-    name: ${{ matrix.os }} / ${{ matrix.python-version }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest]
-        python-version: [3.11]
+    runs-on: ubuntu-latest
+    env:
+        python-version: 3.12
 
     steps:
       - uses: actions/checkout@v4
@@ -32,38 +29,43 @@ jobs:
       - name: Install optipng, dvipng and cm-super
         run: sudo apt-get install -y optipng dvipng cm-super
 
-      - name: Get acc-models-lhc
-        run: git clone -b 2022 https://gitlab.cern.ch/acc-models/acc-models-lhc.git --depth 1
-
-      - name: Move acc-models-lhc to examples folder
-        run: mv acc-models-lhc examples/
-
-      - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python ${{ env.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ matrix.python-version }}
-          cache: pip
+          python-version: ${{ env.python-version }}
+          cache: 'pip'
           cache-dependency-path: '**/pyproject.toml'
 
+      - name: Upgrade pip, setuptools and wheel
+        run: python -m pip install --upgrade pip setuptools wheel
+
       - name: Install package with doc dependencies
         run: python -m pip install ".[docs]"
 
+      - name: Get acc-models-lhc
+        run: git clone -b 2022 https://gitlab.cern.ch/acc-models/acc-models-lhc.git --depth 1
+
+      - name: Move acc-models-lhc to examples folder
+        run: mv acc-models-lhc examples/
+
       - name: Build documentation
         continue-on-error: true
         run: make docs
 
       # Upload artifacts if in PR so reviewers can have a quick look without building documentation from the branch locally
       - name: Upload build artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: success() && github.event_name == 'pull_request'  # only for pushes in PR
         with:
           name: site-build
           path: doc_build
-          retention-days: 7
+          retention-days: 5
 
       # Upload the doc to github pages branch and publish if from a push to master
       - name: Upload documentation to gh-pages
         if: success() && github.ref == 'refs/heads/master'  # only for pushes to master
         uses: JamesIves/github-pages-deploy-action@v4
         with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages
           folder: doc_build
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -11,12 +11,9 @@ on:  # Runs everytime a release is added to the repository
 
 jobs:
   deploy:
-    name: ${{ matrix.os }} / ${{ matrix.python-version }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:  # only lowest supported python on ubuntu-latest
-        os: [ubuntu-latest]
-        python-version: [3.11]
+    runs-on: ubuntu-latest
+    env:
+        python-version: 3.12
 
 
     steps:
@@ -32,5 +29,5 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           verbose: true
-          print_hash: true
+          print-hash: true
           password: ${{ secrets.PYPI_API_TOKEN }}
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -10,13 +10,13 @@ on:  # Runs on any push event to any branch except master (the coverage workflow
       - 'master'
 
 jobs:
-  quick_tests:  # fails here if flaky tests
+  quick_tests:
     name: ${{ matrix.os }} / ${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-22.04, macos-latest, windows-latest]
-        python-version: [3.8, 3.9, "3.10", 3.11, 3.12]
+        os: [ubuntu-22.04, ubuntu-24.04, macos-latest, windows-latest]
+        python-version: ["3.10", 3.11, 3.12]
       fail-fast: false
 
     steps:
@@ -41,8 +41,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-22.04, macos-latest, windows-latest]
-        python-version: [3.8, 3.9, "3.10", 3.11, 3.12]
+        os: [ubuntu-22.04, ubuntu-24.04, macos-latest, windows-latest]
+        python-version: ["3.10", 3.11, 3.12]
       fail-fast: false
 
     steps:

diff --git a/.gitignore b/.gitignore
@@ -253,5 +253,6 @@ Temporary Items
 doc_build/
 docs/gallery/
 docs/gen_modules/
+docs/sg_execution_times.rst
 
 acc-models-lhc/
diff --git a/docs/api/optics.rst b/docs/api/optics.rst
@@ -6,6 +6,9 @@ Optics
 .. automodule:: pyhdtoolkit.optics.beam
    :members:
 
+.. automodule:: pyhdtoolkit.optics.rdt
+   :members:
+
 .. automodule:: pyhdtoolkit.optics.ripken
    :members:
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -14,9 +14,6 @@
 import sys
 import warnings
 
-from sphinx_gallery.scrapers import matplotlib_scraper
-from sphinx_gallery.sorting import ExampleTitleSortKey
-
 import pyhdtoolkit
 
 # ignore numpy warnings, see:
@@ -28,7 +25,7 @@
 warnings.filterwarnings(
     "ignore",
     category=UserWarning,
-    message="Matplotlib is currently using agg, which is a" " non-GUI backend, so cannot show the figure.",
+    message="Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.",
 )
 
 TOPLEVEL_DIR = pathlib.Path(__file__).parent.parent.absolute()
@@ -41,14 +38,6 @@
 # See: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_type_aliases
 autodoc_type_aliases = {"ArrayLike": "ArrayLike"}
 
-# To use SVG outputs when scraping matplotlib figures for the sphinx-gallery
-class matplotlib_svg_scraper(object):
-    def __repr__(self):
-        return self.__class__.__name__
-
-    def __call__(self, *args, **kwargs):
-        return matplotlib_scraper(*args, format="svg", **kwargs)
-
 
 # -- Project information -----------------------------------------------------
 
@@ -145,7 +134,8 @@ def __call__(self, *args, **kwargs):
     "sphinx_copybutton",  # Add a "copy" button to code blocks
     "sphinx_gallery.gen_gallery",  # Build an HTML gallery of examples from a set of Python scripts
     "sphinx_issues",  # Link to project's issue tracker
-    "sphinx_panels",  # Create panels in a grid layout or as drop-downs
+    # "sphinx_panels",  # Create panels in a grid layout or as drop-downs
+    "sphinx_design",  # successor to sphinx_panels, for grid layouts and drop-downs
     "matplotlib.sphinxext.plot_directive",  # Include a Matplotlib plot in a Sphinx document
     "sphinx-prompt",  # prompt symbols will not be copy-pastable
     "sphinx_codeautolink",  # Automatically link example code to documentation source
@@ -176,19 +166,16 @@ def __call__(self, *args, **kwargs):
     "examples_dirs": ["../examples"],  # directory where to find plotting scripts
     "gallery_dirs": ["gallery"],  # directory where to store generated plots
     "filename_pattern": "^((?!sgskip).)*$",  # which files to execute, taken from matplotlib
-    "subsection_order": ExampleTitleSortKey,
-    "within_subsection_order": ExampleTitleSortKey,
-    "reference_url": {"pyhdtoolkit": None},  # Sets up intersphinx in gallery code
     "backreferences_dir": "gen_modules/backreferences",  # where function/class granular galleries are stored
     # Modules for which function/class level galleries are created
     "doc_module": "pyhdtoolkit",
-    "image_scrapers": (matplotlib_svg_scraper(),),  # scrape gallery as SVG
+    "image_scrapers": ("pyhdtoolkit.plotting.utils._matplotlib_svg_scraper",),  # scrape gallery as SVG
     "image_srcset": ["2x"],  # use srcset twice as dense for high-resolution images display
     "min_reported_time": 2,  # minimum execution time to enable reporting
     "remove_config_comments": True,  # remove config comments from the code
     "capture_repr": ("_repr_html_",),
     "compress_images": ("images", "thumbnails", "-o1"),
-    "only_warn_on_example_error": True,  # keep the build going if an example fails, very important for doc workflow
+    "only_warn_on_example_error": True,  # keep the build going if an example fails, important for doc workflow
 }
 
 # Config for the sphinx_panels extension
@@ -352,9 +339,7 @@ def __call__(self, *args, **kwargs):
 # Font configuration
 # Fix fontspec converting " into right curly quotes in PDF
 # cf https://github.com/sphinx-doc/sphinx/pull/6888/
-latex_elements[
-    "fontenc"
-] = r"""
+latex_elements["fontenc"] = r"""
 \usepackage{fontspec}
 \defaultfontfeatures[\rmfamily,\sffamily,\ttfamily]{}
 """
@@ -406,9 +391,7 @@ def __call__(self, *args, **kwargs):
 
 
 # Additional stuff for the LaTeX preamble.
-latex_elements[
-    "preamble"
-] = r"""
+latex_elements["preamble"] = r"""
    % Show Parts and Chapters in Table of Contents
    \setcounter{tocdepth}{0}
    % One line per author on title page