refactor: spring cleaning (#1271)

* sanitize babel calls

* move the gallery directive to an extention folder

* clean test folder

* split __init__.py

* add links between tests

* drop flake8 from pyproject.toml

* rename folder

* update docstring

* only import modules instead of functions

* ignore bootstrap license

* reintegrate modifications from #1264

* typos / docstring improvements / whitespace

* fix: expose traverse_or_findall in utils

---------

Co-authored-by: Daniel McCloy <dan@mccloy.info>

Author: 12rambau

.github/workflows/tests.yml

@@ -39,6 +39,7 @@ jobs:
 
   # run our test suite on various combinations of OS / Python / Sphinx version
   run-pytest:
+    needs: [lint]
     strategy:
       fail-fast: false
       matrix:
@@ -93,6 +94,7 @@ jobs:
 
   # Build our site on the 3 major OSes and check for Sphinx warnings
   build-site:
+    needs: [lint]
     strategy:
       fail-fast: false
       matrix:
@@ -120,6 +122,7 @@ jobs:
 
   # Run local Lighthouse audit against built site
   audit:
+    needs: [build-site]
     strategy:
       matrix:
         os: [ubuntu-latest]
@@ -163,6 +166,7 @@ jobs:
 
   # Generate a profile of the code and upload as an artifact
   profile:
+    needs: [build-site, run-pytest]
     strategy:
       matrix:
         os: [ubuntu-latest]

.pre-commit-config.yaml

@@ -17,22 +17,10 @@ repos:
     hooks:
       - id: black
 
-  - repo: https://github.com/PyCQA/flake8
-    rev: 6.0.0
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: "v0.0.215"
     hooks:
-      - id: flake8
-        additional_dependencies: [Flake8-pyproject]
-
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
-    hooks:
-      - id: check-builtin-literals
-      - id: check-case-conflict
-      - id: check-toml
-      - id: check-yaml
-      - id: debug-statements
-      - id: end-of-file-fixer
-      - id: trailing-whitespace
+      - id: ruff
 
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.3.1

…cs/scripts/gallery_directive/__init__.py docs/_extension/gallery_directive.pydocs/scripts/gallery_directive/__init__.py renamed to docs/_extension/gallery_directive.py docs/scripts/gallery_directive/__init__.py renamed to docs/_extension/gallery_directive.py

@@ -8,14 +8,15 @@
 It currently exists for maintainers of the pydata-sphinx-theme,
 but might be abstracted into a standalone package if it proves useful.
 """
-from yaml import safe_load
-from typing import List
 from pathlib import Path
+from typing import Any, Dict, List
 
 from docutils import nodes
 from docutils.parsers.rst import directives
-from sphinx.util.docutils import SphinxDirective
+from sphinx.application import Sphinx
 from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+from yaml import safe_load
 
 logger = logging.getLogger(__name__)
 
@@ -142,3 +143,19 @@ def run(self) -> List[nodes.Node]:
         if self.options.get("container-class", []):
             container.attributes["classes"] += self.options.get("class", [])
         return [container]
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    """Add custom configuration to sphinx app.
+
+    Args:
+        app: the Sphinx application
+    Returns:
+        the 2 parallel parameters set to ``True``.
+    """
+    app.add_directive("gallery-grid", GalleryDirective)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/conf.py

@@ -1,10 +1,20 @@
+"""Configuration file for the Sphinx documentation builder.
+
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
+
 # -- Path setup --------------------------------------------------------------
 import os
 import sys
+from pathlib import Path
+from typing import Any, Dict
+
 import pydata_sphinx_theme
+from sphinx.application import Sphinx
 
-sys.path.append("scripts")
-from gallery_directive import GalleryDirective
+sys.path.append(str(Path(".").resolve()))
 
 # -- Project information -----------------------------------------------------
 
@@ -22,6 +32,7 @@
     "sphinxext.rediraffe",
     "sphinx_design",
     "sphinx_copybutton",
+    "_extension.gallery_directive",
     # For extension examples and demos
     "ablog",
     "jupyter_sphinx",
@@ -57,7 +68,6 @@
 
 autosummary_generate = True
 
-
 # -- Internationalization ----------------------------------------------------
 
 # specifying the natural language populates some key tags
@@ -223,9 +233,13 @@
 # -- application setup -------------------------------------------------------
 
 
-def setup_to_main(app, pagename, templatename, context, doctree):
+def setup_to_main(
+    app: Sphinx, pagename: str, templatename: str, context, doctree
+) -> None:
+    """Add a function that jinja can access for returning an "edit this page" link pointing to `main`."""
+
     def to_main(link: str) -> str:
-        """Transform "edit on github" links and make sure they always point to the main branch
+        """Transform "edit on github" links and make sure they always point to the main branch.
 
         Args:
             link: the link to the github edit interface
@@ -240,6 +254,17 @@ def to_main(link: str) -> str:
     context["to_main"] = to_main
 
 
-def setup(app):
-    app.add_directive("gallery-grid", GalleryDirective)
+def setup(app: Sphinx) -> Dict[str, Any]:
+    """Add custom configuration to sphinx app.
+
+    Args:
+        app: the Sphinx application
+    Returns:
+        the 2 parralel parameters set to ``True``.
+    """
     app.connect("html-page-context", setup_to_main)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/examples/test_py_module/__init__.py

@@ -0,0 +1 @@
+"""Package definition empty file."""

docs/examples/test_py_module/test.py

@@ -2,7 +2,6 @@
 
 
 class Foo:
-
     """Docstring for class Foo.
 
     This text tests for the formatting of docstrings generated from output
@@ -65,7 +64,6 @@ def add(self, val1, val2):
         :rtype: int
 
         """
-
         return val1 + val2
 
     def capitalize(self, myvalue):
@@ -76,12 +74,10 @@ def capitalize(self, myvalue):
         :rtype: string
 
         """
-
         return myvalue.upper()
 
     def another_function(self, a, b, **kwargs):
-        """
-        Here is another function.
+        """Here is another function.
 
         :param a: The number of green hats you own.
         :type a: int

docs/scripts/generate_collaborators_gallery.py

@@ -1,14 +1,13 @@
-"""Uses the GitHub API to list a gallery of all people with direct access
-to the repository.
-"""
+"""Uses the GitHub API to list a gallery of all people with direct access to the repository."""
 
-from yaml import dump
-from subprocess import run
-import shlex
 import json
+import shlex
 from pathlib import Path
+from subprocess import run
+
+from yaml import dump
 
-COLLABORATORS_API = "https://api.github.com/repos/pydata/pydata-sphinx-theme/collaborators?affiliation=direct"  # noqa
+COLLABORATORS_API = "https://api.github.com/repos/pydata/pydata-sphinx-theme/collaborators?affiliation=direct"
 
 print("Grabbing latest collaborators with GitHub API via GitHub's CLI...")
 out = run(shlex.split(f"gh api {COLLABORATORS_API}"), capture_output=True)

docs/scripts/generate_gallery_images.py

@@ -1,24 +1,21 @@
-"""
-Use playwright to build a gallery of website using this theme
-"""
+"""Use playwright to build a gallery of website using this theme."""
 
 from pathlib import Path
-from yaml import safe_load
 from shutil import copy
-from playwright.sync_api import sync_playwright, TimeoutError
-from rich.progress import track
+
+from playwright.sync_api import TimeoutError, sync_playwright
 from rich import print
+from rich.progress import track
+from yaml import safe_load
 
 
-def regenerate_gallery():
-    """
-    Regenerate images of snapshots for our gallery.
+def regenerate_gallery() -> None:
+    """Regenerate images of snapshots for our gallery.
 
     This function should only be triggered in RTD builds as it increases the build
     time by 30-60s. Developers can still execute this function from time to time to
     populate their local gallery images with updated files.
     """
-
     # get the existing folders path
     _static_dir = Path(__file__).parents[1] / "_static"
 

docs/scripts/update_kitchen_sink.py

@@ -1,5 +1,7 @@
-from urllib.request import urlopen
+"""Script run to update the kitchen sink from https://sphinx-themes.org."""
+
 from pathlib import Path
+from urllib.request import urlopen
 
 EXTRA_MESSAGE = """\
 .. note::
@@ -11,7 +13,7 @@
       :color: primary
 
       Go to Sphinx Themes
-"""  # noqa
+"""
 
 kitchen_sink_files = [
     "admonitions.rst",
@@ -29,7 +31,7 @@
 path_sink = Path(__file__).parent.parent / "examples" / "kitchen-sink"
 for ifile in kitchen_sink_files:
     print(f"Reading {ifile}...")
-    url = f"https://github.com/sphinx-themes/sphinx-themes.org/raw/master/sample-docs/kitchen-sink/{ifile}"  # noqa
+    url = f"https://github.com/sphinx-themes/sphinx-themes.org/raw/master/sample-docs/kitchen-sink/{ifile}"
     text = urlopen(url).read().decode()
     # The sphinx-themes docs expect Furo to be installed, so we overwrite w/ PST
     text = text.replace("src/furo", "src/pydata_sphinx_theme")