feat: drop python3.8 support, add 3.12 testing (#90) adds nofollow source links

SecondSkoll · web-flow · commit e00ce63d4b22 · 2025-07-09T12:14:16.000+10:00
* feat: step towards frozen requirements

* feat: pin to python 3.10 and all versions

* fix: update github workflow files

* fix: RTD python version

* remove version pinning

* drop python3.8 add 3.12

* fix: type validation

* prevent indexing source pages via crawling
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -47,7 +47,7 @@ jobs:
   unit:
     strategy:
       matrix:
-        platform: [ubuntu-20.04, ubuntu-22.04, windows-latest]
+        platform: [ubuntu-22.04, windows-latest]
     runs-on: ${{ matrix.platform }}
     steps:
       - uses: actions/checkout@v4
@@ -57,7 +57,6 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: |
-            3.8
             3.10
             3.11
             3.12-dev
@@ -88,7 +87,7 @@ jobs:
   integration:
     strategy:
       matrix:
-        platform: [ubuntu-20.04, ubuntu-22.04, windows-latest]
+        platform: [ubuntu-22.04, windows-latest]
     runs-on: ${{ matrix.platform }}
     steps:
       - uses: actions/checkout@v4
@@ -98,7 +97,6 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: |
-            3.8
             3.10
             3.11
             3.12-dev
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -17,7 +17,7 @@ formats:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.8"  # We still support Python 3.8 for now.
+    python: "3.10"  # We only support 3.10+.
   jobs:
     build:
       epub:
diff --git a/canonical_sphinx/__init__.py b/canonical_sphinx/__init__.py
@@ -14,7 +14,7 @@
 # You should have received a copy of the GNU General Public License along
 # with this program.  If not, see <http://www.gnu.org/licenses/>.
 """Sphinx configuration, extension and theme for Canonical documentation."""
-from typing import List, Optional, Any, Dict
+from typing import Any
 
 from sphinx.application import Sphinx
 
@@ -35,7 +35,7 @@
         __version__ = "dev"
 
 
-def hello(people: Optional[List[Any]] = None) -> None:
+def hello(people: list[Any] | None = None) -> None:
     """Says hello."""
     print("Hello *craft team!")
     if people:
@@ -48,7 +48,7 @@ def copy_custom_files(app: Sphinx) -> None:
         shutil.copytree(str(theme_dir / "PDF"), app.outdir, dirs_exist_ok=True)
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     """Configure the main extension and theme."""
     app.setup_extension("canonical_sphinx.config")
     app.connect(  # pyright: ignore [reportUnknownMemberType]
diff --git a/canonical_sphinx/config.py b/canonical_sphinx/config.py
@@ -18,26 +18,59 @@
 import importlib.util
 import os
 from pathlib import Path
-from typing import Any, Dict
+from typing import Any
 
 from sphinx.application import Sphinx
 from sphinx.config import Config
 from sphinx.errors import ConfigError
 from sphinx.util import logging
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+class SphinxConfig(Config):
+    """Expanded class for linting config options."""
+
+    notfound_urls_prefix: str
+    html_theme: str
+    html_last_updated_fmt: str
+    html_permalinks_icon: str
+    html_theme_options: dict[str, Any]
+    html_favicon: str
+    notfound_template: str
+    latex_engine: str
+    latex_show_pagerefs: bool
+    latex_show_urls: str
+    latex_table_style: list[str]
+    latex_config: str
+    latex_elements: dict[str, Any]
+    html_copy_source: bool
+    html_show_sourcelink: bool
+
+    def __init__(self) -> None:
+        pass
+
+
+def setup(app: Sphinx) -> dict[str, Any]:
     """Perform the main configuration and theme-setting."""
     # These are options that the user can set on their "conf.py"
     # (many options are still missing).
-    app.add_config_value(
+    app.add_config_value(  # pyright: ignore [reportUnknownMemberType]
         "disable_feedback_button",
         default=False,
         rebuild="env",
         types=bool,
     )
-    app.add_config_value("slug", default="", rebuild="env", types=str)
-    app.add_config_value("epub_build", default=False, rebuild="env", types=bool)
+    app.add_config_value(  # pyright: ignore [reportUnknownMemberType]
+        "slug",
+        default="",
+        rebuild="env",
+        types=str,
+    )
+    app.add_config_value(  # pyright: ignore [reportUnknownMemberType]
+        "epub_build",
+        default=False,
+        rebuild="env",
+        types=bool,
+    )
 
     extra_extensions = [
         "myst_parser",
@@ -88,7 +121,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     }
 
 
-def config_inited(app: Sphinx, config: Config) -> None:  # noqa: PLR0915, PLR0912
+def config_inited(app: Sphinx, config: SphinxConfig) -> None:  # noqa: PLR0915, PLR0912
     """Read user-provided values and setup defaults."""
     # Get the Sphinx warning logger early
     logger = logging.getLogger(__name__)
@@ -184,7 +217,9 @@ def config_inited(app: Sphinx, config: Config) -> None:  # noqa: PLR0915, PLR091
     with Path.open(theme_dir / "PDF/latex_elements_template.txt", "r+") as file:
         config.latex_config = file.read()
 
-    if config.latex_elements == {}:
+    if (
+        config.latex_elements == {}
+    ):  # pyright: ignore [reportUnnecessaryComparison] type: # ignore[comparison-overlap]
 
         config.latex_elements = ast.literal_eval(config.latex_config)
 
diff --git a/canonical_sphinx/theme/__init__.py b/canonical_sphinx/theme/__init__.py
@@ -14,13 +14,13 @@
 # You should have received a copy of the GNU General Public License along
 # with this program.  If not, see <http://www.gnu.org/licenses/>.
 """Sphinx theme for Canonical documentation."""
-from typing import Any, Dict
+from typing import Any
 from pathlib import Path
 
 from sphinx.application import Sphinx
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     """Add "canonical_sphinx_theme" as a valid html theme."""
     app.add_html_theme("canonical_sphinx_theme", str(Path(__file__).parent))
     return {
diff --git a/canonical_sphinx/theme/templates/components/view-this-page.html b/canonical_sphinx/theme/templates/components/view-this-page.html
@@ -0,0 +1,23 @@
+{% extends "basic-ng/components/view-this-page.html" %}
+{% from "basic-ng/components/view-this-page.html" import determine_page_view_link with context %}
+
+{%- macro furo_view_button(url) -%}
+<div class="view-this-page">
+  <a class="muted-link" href="{{ url }}" rel="nofollow" title="{{ _("View this page") }}">
+    <svg><use href="#svg-eye"></use></svg>
+    <span class="visually-hidden">{{ _("View this page") }}</span>
+  </a>
+</div>
+{%- endmacro -%}
+
+{% block link_available -%}
+{{ furo_view_button(determine_page_view_link()) }}
+{%- endblock %}
+
+{% block link_not_available %}
+{# Make nice things happen, on Read the Docs #}
+{%- if READTHEDOCS and conf_py_path and page_source_suffix and github_user != "None" and github_repo != "None" and github_version and pagename and page_source_suffix %}
+  {% set url = "https://github.com/" + github_user + "/" + github_repo + "/blob/" + github_version + conf_py_path + pagename + page_source_suffix + "?plain=true" %}
+  {{ furo_view_button(url) }}
+{%- endif -%}
+{% endblock %}
diff --git a/pyproject.toml b/pyproject.toml
@@ -2,7 +2,7 @@
 name = "canonical-sphinx"
 dynamic = ["version", "readme"]
 dependencies = [
-    "sphinx>=7.1.2,<8",
+    "Sphinx",
     "furo",
     "myst-parser",
     "linkify-it-py",
@@ -11,9 +11,9 @@ classifiers = [
     "Development Status :: 1 - Planning",
     "License :: OSI Approved :: GNU General Public License (GPL)",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.10",
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 
 [project.scripts]
 canonical-sphinx-hello = "canonical_sphinx:hello"
@@ -22,9 +22,9 @@ canonical-sphinx-hello = "canonical_sphinx:hello"
 full = [
     "canonical-sphinx-extensions",
     "sphinx-copybutton",
-    "sphinx-design",
+    "sphinx_design",
     "sphinx-notfound-page",
-    "sphinx-reredirects",
+    "sphinx_reredirects",
     "sphinx-tabs",
     "sphinxcontrib-jquery",
     "sphinxext-opengraph",
@@ -94,7 +94,7 @@ namespaces = false
 canonical_sphinx = ["theme/PDF/*.ttf", "theme/PDF/*.pdf", "theme/PDF/*.png", "theme/PDF/*.txt"]
 
 [tool.black]
-target-version = ["py38"]
+target-version = ["py310"]
 
 [tool.codespell]
 ignore-words-list = "buildd,crate,keyserver,comandos,ro,dedent,dedented"
@@ -128,7 +128,7 @@ exclude_also = [
 
 [tool.pyright]
 strict = ["canonical_sphinx"]
-pythonVersion = "3.8"
+pythonVersion = "3.10"
 pythonPlatform = "Linux"
 exclude = [
     "**/.*",
@@ -139,7 +139,7 @@ exclude = [
 ]
 
 [tool.mypy]
-python_version = "3.8"
+python_version = "3.10"
 exclude = [
     "build",
     "tests",
@@ -166,7 +166,7 @@ strict = false
 
 [tool.ruff]
 line-length = 88
-target-version = "py38"
+target-version = "py310"
 src = ["canonical_sphinx", "tests"]
 extend-exclude = [
     "docs",
diff --git a/tox.ini b/tox.ini
@@ -3,7 +3,7 @@ env_list =  # Environments to run when called with no parameters.
     format-{black,ruff,codespell}
     pre-commit
     lint-{black,ruff,mypy,pyright,shellcheck,codespell,docs,yaml}
-    unit-py3.{8,10,11}
+    unit-py3.{10,11,12}
     integration-py3.10
 # Integration tests probably take a while, so we're only running them on Python
 # 3.10, which is included in core22.
@@ -42,15 +42,15 @@ extras = dev
 allowlist_externals = mkdir
 commands_pre = mkdir -p {tox_root}/results
 
-[testenv:{unit,integration}-py3.{8,9,10,11,12}]  # Configuration for all tests using pytest
+[testenv:{unit,integration}-py3.{10,11,12}]  # Configuration for all tests using pytest
 base = testenv, test
 description =
     unit: Run unit tests with pytest
     integration: Run integration tests with pytest
 labels =
-    py3.{8,10,11}: tests
-    unit-py3.{8,10,11}: unit-tests
-    integration-py3.{8,10,11}: integration-tests
+    py3.{10,11,12}: tests
+    unit-py3.{10,11,12}: unit-tests
+    integration-py3.{10,11,12}: integration-tests
 change_dir =
     unit: tests/unit
     integration: tests/integration
