Check the website field against the declared documentation URL

The check only asserted the field was non-empty, so a documentation site that
moves to a new domain leaves the repository sidebar pointing at the origin it
left, with nothing to report it: `meta-package-manager` has been in that state
since its docs moved to `mpm.run`, every published page naming the new origin
as canonical while the sidebar still sends visitors to `github.io`. A trailing
slash and the case of the scheme and host are ignored, since GitHub stores the
website field with the slash a browser appends and `[project.urls]` is usually
written without one.

Author: kdeldycke

changelog.md

@@ -5,6 +5,8 @@
 > [!WARNING]
 > This version is **not released yet** and is under active development.
 
+- `lint-repo` now warns when a Sphinx project's GitHub website field differs from the documentation URL declared in `[project.urls]`.
+
 ## [`7.11.0` (2026-08-13)](https://github.com/kdeldycke/repomatic/compare/v7.10.0...v7.11.0)
 
 - **Breaking:** `labels.content-rules` and `labels.file-rules` are now tables mapping each label to its patterns, like `"📚 docs" = ["docs/**"]`. The array-of-tables form and its `actions/labeler` v5 matcher schema are gone; an un-migrated config is ignored with a warning.

docs/workflows.md

@@ -399,6 +399,7 @@ None of these jobs read a label config committed to the repository. `labels.toml
 #### 🏠 Lint repository metadata (`lint-repo`)
 
 - Validates repository metadata (package name, Sphinx docs, project description) and Dependabot configuration using [`repomatic lint-repo`](https://github.com/kdeldycke/repomatic/blob/main/repomatic/cli.py). Reads `pyproject.toml` directly. When `REPOMATIC_PAT` is configured, also validates PAT capabilities (contents, issues, pull requests, Dependabot alerts, workflows permissions). Warns when the fork PR workflow approval policy is weaker than `first_time_contributors`. Warns about missing `VIRUSTOTAL_API_KEY` when Nuitka binary compilation is active. Warns about missing `REPOMATIC_NOTIFICATIONS_PAT` when the unsubscribe workflow is enabled.
+- Warns when a Sphinx project's GitHub website field does not name the documentation URL it declares in `[project.urls]` (`Documentation`, then `Docs`). A trailing slash and the case of the scheme and host are ignored, since GitHub stores the website field with the slash a browser appends. Moving a documentation site to a new domain is what this catches: Sphinx renders `<link rel="canonical">` from `html_baseurl`, so every published page names the new origin while the repository sidebar keeps sending visitors to the old one. A project declaring no documentation URL keeps the presence-only check
 - Warns when a release download URL in `docs/install.md` names a file its release does not carry. The release freeze pins those URLs before the binaries exist, so a failed build lane leaves the guide advertising 404s until the next release moves past it: this is the check that surfaces the gap instead of leaving it for a user to hit. Versionless `releases/latest/download` URLs are checked against the latest published release too, and rot longer: nothing rewrites them at release time, so a renamed asset leaves one pointing at a 404 indefinitely
 - **Requires**:
   - Python package (with a `pyproject.toml` file)

repomatic/cli.py

@@ -188,6 +188,7 @@
 )
 from .lint_repo import (
     KNOWN_RUNNERS,
+    documentation_url,
     run_repo_lint,
 )
 from .mailmap import Mailmap, remove_header
@@ -2075,7 +2076,8 @@ def lint_repo(
     \b
     Checks:
       - Package name vs repository name (warning).
-      - Website field set for Sphinx projects (warning).
+      - Website field set for Sphinx projects, and matching the documentation
+        URL declared in [project.urls] (warning).
       - Repository description matches project description (error).
       - GitHub topics subset of pyproject.toml keywords (warning).
       - Funding file present when owner has GitHub Sponsors (warning).
@@ -2114,12 +2116,15 @@ def lint_repo(
         # Extract repo name from owner/repo format.
         repo_name = repo.split("/")[-1] if "/" in repo else repo
 
-    # Derive package_name, is_sphinx, project_description, keywords from pyproject.toml.
+    # Derive package_name, is_sphinx, project_description, docs_url and keywords
+    # from pyproject.toml.
     metadata = Metadata()
     package_name = get_project_name()
     is_sphinx = metadata.is_sphinx
     project_description = metadata.project_description
-    keywords = metadata.pyproject_toml.get("project", {}).get("keywords")
+    project_table = metadata.pyproject_toml.get("project", {})
+    docs_url = documentation_url(project_table.get("urls"))
+    keywords = project_table.get("keywords")
 
     config = get_tool_config(ctx)
     nuitka_active = config.nuitka_enabled and bool(metadata.script_entries)
@@ -2130,6 +2135,7 @@ def lint_repo(
         is_package=metadata.is_python_package,
         is_sphinx=is_sphinx,
         project_description=project_description,
+        docs_url=docs_url,
         keywords=keywords,
         repo=repo if repo else None,
         has_pat=has_pat,

repomatic/lint_repo.py

@@ -32,6 +32,7 @@
 from functools import cached_property
 from pathlib import Path
 from typing import NamedTuple
+from urllib.parse import urlsplit
 
 import yaml
 from click_extra import echo
@@ -59,7 +60,17 @@
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Iterator
+    from collections.abc import Callable, Iterable, Iterator, Mapping
+
+DOCS_URL_KEYS = ("documentation", "docs")
+"""Keys in `[project.urls]` naming the published documentation site.
+
+Checked in priority order, and looked up in a lowercased index of the
+project's own keys: PEP 621 leaves the spelling to the project, so
+`Documentation`, `documentation` and `Docs` all occur in the wild. Mirrors the
+same convention {data}`repomatic.pypi._SOURCE_URL_KEYS` applies to the PyPI
+copy of the same mapping.
+"""
 
 WORKFLOW_DIR = Path(WORKFLOW_TARGET_ROOT)
 """Directory every workflow check walks.
@@ -206,14 +217,76 @@ def check_package_name_vs_repo(package_name: str | None, repo_name: str) -> Chec
     return CheckResult(True, f"Package name '{package_name}' matches repository name.")
 
 
+def _url_key(url: str) -> tuple[str, str, str, str, str]:
+    """Reduce a URL to what two spellings of the same address share.
+
+    Lowercases the scheme and host, which are case-insensitive per
+    [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986#section-3.1), and
+    drops a trailing slash. GitHub stores the website field with the trailing
+    slash a browser appends, while `[project.urls]` is usually written without
+    one, so comparing raw strings would report a correctly configured
+    repository as a mismatch.
+
+    Every other difference survives. A path's case is significant, and `http`
+    and `https` really are two origins: those are the splits a comparison
+    exists to surface, not noise to smooth over.
+    """
+    parts = urlsplit(url.strip())
+    return (
+        parts.scheme.lower(),
+        parts.netloc.lower(),
+        parts.path.rstrip("/"),
+        parts.query,
+        parts.fragment,
+    )
+
+
+def documentation_url(project_urls: Mapping[str, str] | None) -> str | None:
+    """The documentation site a project declares in `[project.urls]`.
+
+    :param project_urls: The `[project.urls]` mapping, keys untouched.
+    :return: The first URL found per {data}`DOCS_URL_KEYS`, or `None` when the
+        project declares none.
+    """
+    if not project_urls:
+        return None
+    by_key = {key.lower(): str(value).strip() for key, value in project_urls.items()}
+    for key in DOCS_URL_KEYS:
+        if candidate := by_key.get(key):
+            return candidate
+    return None
+
+
 def check_website_for_sphinx(
-    repo: str, is_sphinx: bool, homepage_url: str | None = None
+    repo: str,
+    is_sphinx: bool,
+    homepage_url: str | None = None,
+    docs_url: str | None = None,
 ) -> CheckResult:
-    """Check that Sphinx projects have a website set.
+    """Check that a Sphinx project's website field names its documentation.
+
+    GitHub renders the website field in the repository sidebar, and for a
+    project publishing Sphinx documentation that is where a visitor expects to
+    land. So the check has two halves: the field is set at all, and it names
+    the site the project itself declares under {data}`DOCS_URL_KEYS`.
+
+    The second half is what a documentation move leaves behind. Sphinx emits
+    `<link rel="canonical">` from `html_baseurl`, and a `conf.py` commonly
+    derives that from the same `[project.urls]` entry, so a project that moves
+    to a new domain has every published page naming the new origin as canonical
+    while the sidebar keeps sending visitors to the one it replaced. Nothing
+    but a reader noticing connects the two.
+
+    ```{note}
+    A project declaring no documentation URL gets the presence half only. The
+    comparison needs the project to have named an expected answer, and nothing
+    here invents one from the repository slug.
+    ```
 
     :param repo: Repository in 'owner/repo' format.
     :param is_sphinx: Whether the project uses Sphinx documentation.
     :param homepage_url: The homepage URL from API (to avoid duplicate calls).
+    :param docs_url: Documentation URL declared in `[project.urls]`.
     :return: A `CheckResult`.
     """
     if not is_sphinx:
@@ -226,7 +299,20 @@ def check_website_for_sphinx(
     if not homepage_url:
         msg = "Sphinx documentation detected but repository website field is not set."
         return CheckResult(False, msg)
-    return CheckResult(True, f"Website field is set: {homepage_url}")
+
+    if not docs_url:
+        return CheckResult(True, f"Website field is set: {homepage_url}")
+
+    if _url_key(homepage_url) != _url_key(docs_url):
+        msg = (
+            f"Repository website field '{homepage_url}' differs from the"
+            f" documentation URL '{docs_url}' declared in [project.urls]."
+        )
+        return CheckResult(False, msg)
+
+    return CheckResult(
+        True, f"Website field matches the documentation URL: {homepage_url}"
+    )
 
 
 def check_description_matches(
@@ -1840,6 +1926,9 @@ class LintContext:
     project_description: str | None = None
     """Description from `pyproject.toml`."""
 
+    docs_url: str | None = None
+    """Documentation site declared in `[project.urls]`, per {data}`DOCS_URL_KEYS`."""
+
     keywords: list[str] | None = None
     """Keywords list from `pyproject.toml`."""
 
@@ -1963,7 +2052,10 @@ def _pat_permissions(ctx: LintContext) -> Iterator[CheckResult]:
     RepoCheck(
         "website-for-sphinx",
         lambda ctx: check_website_for_sphinx(
-            ctx.repo or "", ctx.is_sphinx, ctx.repo_metadata.get("homepageUrl")
+            ctx.repo or "",
+            ctx.is_sphinx,
+            ctx.repo_metadata.get("homepageUrl"),
+            ctx.docs_url,
         ),
         applies=lambda ctx: ctx.is_sphinx,
     ),
@@ -2093,6 +2185,7 @@ def run_repo_lint(
     is_package: bool = False,
     is_sphinx: bool = False,
     project_description: str | None = None,
+    docs_url: str | None = None,
     keywords: list[str] | None = None,
     repo: str | None = None,
     has_pat: bool = False,
@@ -2113,6 +2206,7 @@ def run_repo_lint(
     :param is_package: Whether the project builds a distributable package.
     :param is_sphinx: Whether the project uses Sphinx documentation.
     :param project_description: Description from pyproject.toml.
+    :param docs_url: Documentation URL declared in `[project.urls]`.
     :param keywords: Keywords list from pyproject.toml.
     :param repo: Repository in 'owner/repo' format.
     :param has_pat: Whether `GH_TOKEN` contains `REPOMATIC_PAT`.
@@ -2130,6 +2224,7 @@ def run_repo_lint(
         is_package=is_package,
         is_sphinx=is_sphinx,
         project_description=project_description,
+        docs_url=docs_url,
         keywords=keywords,
         repo=repo,
         has_pat=has_pat,

tests/test_lint_repo.py

@@ -46,6 +46,7 @@
     check_topics_subset_of_keywords,
     check_website_for_sphinx,
     check_workflow_permissions,
+    documentation_url,
     get_repo_metadata,
     run_repo_lint,
 )
@@ -145,6 +146,95 @@ def test_sphinx_fetches_metadata():
         mock_get.assert_called_once_with("owner/repo")
 
 
+@pytest.mark.parametrize(
+    ("project_urls", "expected"),
+    (
+        (None, None),
+        ({}, None),
+        ({"Homepage": "https://papaya.example"}, None),
+        (
+            {"Documentation": "https://docs.papaya.example"},
+            "https://docs.papaya.example",
+        ),
+        # PEP 621 fixes neither the case nor the wording of the key.
+        (
+            {"documentation": "https://docs.papaya.example"},
+            "https://docs.papaya.example",
+        ),
+        ({"DOCS": "https://docs.papaya.example"}, "https://docs.papaya.example"),
+        # `Documentation` outranks `Docs` when a project declares both.
+        (
+            {"Docs": "https://kiwi.example", "Documentation": "https://papaya.example"},
+            "https://papaya.example",
+        ),
+        # An empty value is not a declaration.
+        (
+            {"Documentation": "  ", "Docs": "https://papaya.example"},
+            "https://papaya.example",
+        ),
+    ),
+)
+def test_documentation_url(project_urls, expected):
+    """Resolve the documentation site a project declares in `[project.urls]`."""
+    assert documentation_url(project_urls) == expected
+
+
+@pytest.mark.parametrize(
+    ("homepage_url", "docs_url"),
+    (
+        # GitHub stores the trailing slash a browser appends, while
+        # `[project.urls]` is usually written without one.
+        ("https://papaya.example/", "https://papaya.example"),
+        ("https://papaya.example", "https://papaya.example/"),
+        ("https://kiwi.github.io/papaya/", "https://kiwi.github.io/papaya"),
+        # Scheme and host are case-insensitive per RFC 3986.
+        ("HTTPS://Papaya.Example", "https://papaya.example"),
+    ),
+)
+def test_sphinx_website_matches_docs_url(homepage_url, docs_url):
+    """Pass when the website field and the declared docs URL name one address."""
+    result = check_website_for_sphinx(
+        "owner/repo", is_sphinx=True, homepage_url=homepage_url, docs_url=docs_url
+    )
+    assert result.passed is True
+    assert "matches" in result.message
+
+
+@pytest.mark.parametrize(
+    ("homepage_url", "docs_url"),
+    (
+        # The move this check exists to catch: the documentation gained a
+        # domain and the sidebar kept pointing at the origin it left.
+        ("https://kiwi.github.io/papaya", "https://papaya.example"),
+        # A path's case is significant, unlike a host's.
+        ("https://papaya.example/Docs", "https://papaya.example/docs"),
+        # Two origins, not one.
+        ("http://papaya.example", "https://papaya.example"),
+        ("https://papaya.example/docs", "https://papaya.example/manual"),
+    ),
+)
+def test_sphinx_website_differs_from_docs_url(homepage_url, docs_url):
+    """Fail when the website field names something other than the docs URL."""
+    result = check_website_for_sphinx(
+        "owner/repo", is_sphinx=True, homepage_url=homepage_url, docs_url=docs_url
+    )
+    assert result.passed is False
+    assert homepage_url in result.message
+    assert docs_url in result.message
+
+
+def test_sphinx_website_without_declared_docs_url():
+    """Keep the presence-only check when the project declares no docs URL."""
+    result = check_website_for_sphinx(
+        "owner/repo",
+        is_sphinx=True,
+        homepage_url="https://kiwi.github.io/papaya",
+        docs_url=None,
+    )
+    assert result.passed is True
+    assert "is set" in result.message
+
+
 def test_descriptions_match():
     """No error when descriptions match."""
     result = check_description_matches(
@@ -244,6 +334,24 @@ def test_website_warning(capsys):
         assert "::warning::" in captured.out
 
 
+def test_website_docs_url_mismatch_warning(capsys):
+    """A website field pointing away from the docs URL warns without failing."""
+    with patch("repomatic.lint_repo.get_repo_metadata") as mock_get:
+        mock_get.return_value = {
+            "homepageUrl": "https://kiwi.github.io/papaya",
+            "description": None,
+        }
+        exit_code = run_repo_lint(
+            is_sphinx=True,
+            docs_url="https://papaya.example",
+            repo="owner/repo",
+        )
+        assert exit_code == 0
+        captured = capsys.readouterr()
+        assert "::warning::" in captured.out
+        assert "https://papaya.example" in captured.out
+
+
 @pytest.mark.parametrize(
     ("unsubscribe_active", "has_notifications_pat", "expected"),
     (