Proposal: add new builder that checks if hardcoded URLs can be replaced with crossrefs by hoefling · Pull Request #9626 · sphinx-doc/sphinx

hoefling · 2021-09-11T15:46:03Z

Subject: (copied from pytest-dev/pytest#9082)

This PR adds a new no-op Sphinx builder named crossrefcheck that checks whether a hardcoded URL in the text can be replaced with a crossreference from one of the inventories configured in intersphinx_mapping.

Feature or Bugfix

Feature

Purpose

If a hardcoded link can be replaced with a crossref, crossrefcheck will emit a warning like this:

pytest/doc/en/reference/reference.rst:127: WARNING: hardcoded link 'https://docs.python.org/3/library/unittest.html#unittest.TestCase.assertAlmostEqual' could be replaced by a cross-reference to 'python' inventory (try using ':py:meth:`unittest.TestCase.assertAlmostEqual`' instead)

If a replacement suggestion is printed, the hardcoded URL can be safely replaced with that suggestion.

Usage

$ sphinx-build -b crossrefcheck doc build

Caveats

The builder is not able to catch the URLs for the internal docs. This is because no information is known about the URL the docs will be hosted at. Thus, if e.g. links to https://docs.pytest.org should be checked as well in the docs for the pytest project, it is best to extend intersphinx_mapping. Example:

 intersphinx_mapping = {
    ...
    "pytest-latest": ("https://docs.pytest.org/en/latest", None),
    "pytest-stable": ("https://docs.pytest.org/en/stable", None),
    "pytest-6": ("https://docs.pytest.org/en/6.2.x", None),
 }

If a URL is reported without a suggestion, it usually indicates that either:

a link points to a section or paragraph that doesn't have a Sphinx reference defined - the external docs should be updated then,
or the reference was changed, so the link is outdated (but still valid!). In this case, it's usually best to check the docs source to find the new correct ref name.

Example output from running over `Sphinx` repository

sphinx/doc/development/tutorials/helloworld.rst:132: WARNING: hardcoded link 'https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH' could be replaced by a cross-reference to 'python' inventory (try using ':std:envvar:`PYTHONPATH`' instead)
sphinx/doc/development/tutorials/helloworld.rst:151: WARNING: hardcoded link 'https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH' could be replaced by a cross-reference to 'python' inventory (try using ':std:envvar:`PYTHONPATH`' instead)
sphinx/doc/development/tutorials/todo.rst:294: WARNING: hardcoded link 'https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH' could be replaced by a cross-reference to 'python' inventory (try using ':std:envvar:`PYTHONPATH`' instead)
sphinx/doc/examples.rst:95: WARNING: hardcoded link 'https://docs.python.org/3/' could be replaced by a cross-reference to 'python' inventory (no suggestion)
sphinx/doc/man/sphinx-apidoc.rst:17: WARNING: hardcoded link 'https://docs.python.org/3/library/fnmatch.html' could be replaced by a cross-reference to 'python' inventory (try using ':std:doc:`library/fnmatch`' instead)
sphinx/doc/usage/configuration.rst:570: WARNING: hardcoded link 'https://requests.readthedocs.io/en/master/' could be replaced by a cross-reference to 'requests' inventory (no suggestion)
sphinx/doc/usage/restructuredtext/directives.rst:1000: WARNING: hardcoded link 'https://docs.python.org/3/reference/lexical_analysis.html#identifiers' could be replaced by a cross-reference to 'python' inventory (try using ':std:ref:`identifiers`' instead)

hoefling · 2021-09-11T15:50:06Z

The original proposal was made in pytest-dev/pytest#9082, where it was suggested to add the builder to Sphinx instead, so it can be reused in multiple projects. Please note that this PR isn't ready to be merged yet (e.g. missing tests and proper documentation). Its purpose is merely to propose the builder first and check whether @tk0miya would approve the general idea.

tk0miya · 2021-09-12T09:15:11Z

Agreed. This must be worthy. So +1 for merging this into the core. But I'm not sure this should be added as a standalone builder or an additional feature of linkcheck builder. Is there any reason to make this standalone?

jakobandersen · 2021-09-12T09:26:11Z

This is pretty cool. Implementation-wise I'm wondering if it is possible to have a bit more indirection such that this doesn't access the intersphinx inventory directly, but asks the intersphinx extension to lookup an URL and return the necessary information.
The issue is that in order to update intersphinx to work in all cases the inventory format needs to change so it would be good if the rest of Sphinx doesn't assume a specific inventory format.

Zac-HD · 2021-09-13T00:18:07Z

I'm not sure this should be added as a standalone builder or an additional feature of linkcheck builder. Is there any reason to make this standalone?

I would prefer a standalone crossref builder so I can run it offline in CI, where linkcheck can fail due to flaky websites or network issues.

hoefling · 2021-09-25T12:47:43Z

Since the changes are added to Sphinx itself, the builder might not be necessary at all, depending on how deeply those warnings should be integrated. E.g. I could add a SphinxPostTransform directly to sphinx.ext.intersphinx and emit the warnings by default when the docs are built and the intersphinx extension is enabled. @tk0miya @Zac-HD what do you think? I have added a prototype in the latest commit where the warnings are emitted directly on doc build and no special builder is needed. This also simplifies the changes a lot (one new SphinxPostTransform, one extra utility function). The move of the code to intersphinx also addresses @jakobandersen's comment, since all the logic is now internal to intersphinx extension.

Zac-HD · 2021-09-25T13:22:20Z

That would be fantastic for all my use-cases!

RonnyPfannschmidt · 2021-09-25T13:36:02Z

follow-up idea - for linkcheck identify links that are in locations where a intersphinx ref could be used or added (for links to other docs that use sphinx but are not declared as intersphinx

hoefling · 2021-09-26T19:59:12Z

@tk0miya gentle ping for a review.

hoefling · 2021-12-09T09:14:50Z

@tk0miya gentle ping. Maybe it's still not too late for this to become part of 4.4?

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

…e in docstring Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

Signed-off-by: Oleg Hoefling <oleg.hoefling@gmail.com>

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

hoefling · 2023-08-29T14:23:24Z

@AA-Turner done 😎

picnixz · 2023-08-29T14:41:19Z

CHANGES

 * #9075: autodoc: Add a config variable :confval:`autodoc_typehints_format`
  to suppress the leading module names of typehints of function signatures (ex.
  ``io.StringIO`` -> ``StringIO``)
+* #9626: intersphinx: Emit warning if a hardcoded link is replaceable


This should be moved to the latest version now!

picnixz · 2023-08-29T14:43:04Z

doc/conf.py


 intersphinx_mapping = {
    'python': ('https://docs.python.org/3/', None),
-    'requests': ('https://requests.readthedocs.io/en/latest/', None),


Let's minimize the changes (unless there is a reason to change this)

picnixz · 2023-08-29T14:46:21Z

sphinx/ext/intersphinx.py

 import time
 from os import path
-from typing import TYPE_CHECKING, cast
+from typing import IO, TYPE_CHECKING, Any, cast


Where do you need IO and Any as runtime types?

picnixz · 2023-08-29T15:07:33Z

tests/test_ext_intersphinx.py

+# Project: foo
+# Version: 2.0
+# The remainder of this file is compressed with zlib.
+''' + zlib.compress(b'')


Hardcode the value of zlib.compress(..) and put a comment.

Other suggestion: make these constants private or create a class testing find_replacements so that the logic is "contained" (with a class-based approach you could put the setup of your test in a method).

picnixz · 2023-08-29T15:08:25Z

tests/test_ext_intersphinx.py

+    normalize_intersphinx_mapping(app, app.config)
+    load_mappings(app)
+
+    assert next(find_replacements(app, 'https://example.com'), None) is None


assert not list(...)

picnixz · 2023-08-29T15:08:58Z

tests/test_ext_intersphinx.py

+    load_mappings(app)
+
+    uri = 'https://example.com/foo.html#module-module1'
+    replacement = next(find_replacements(app, uri), None)


assert not list(...)

picnixz · 2023-08-29T15:10:20Z

tests/test_ext_intersphinx.py

+    load_mappings(app)
+
+    uri = 'https://docs.python.org/foo.html#module-module1'
+    replacement = next(find_replacements(app, uri))


replacements = list(...) assert len(replacements) == ... assert replacements[0] == ... ...

or

assert list(...) == [...]

hoefling mentioned this pull request Sep 11, 2021

WIP: add crossrefs checker for documentation linting pytest-dev/pytest#9082

Closed

tk0miya added builder extensions:intersphinx type:proposal a feature suggestion labels Sep 12, 2021

hoefling force-pushed the crossrefcheck-builder branch from 58ae250 to 241a390 Compare September 25, 2021 12:53

Zac-HD mentioned this pull request Sep 26, 2021

Use Sphinx intersphinx or extlinks for common cross-refs, not full URLs pytest-dev/pytest#9081

Closed

3 tasks

hoefling force-pushed the crossrefcheck-builder branch 2 times, most recently from 4ee525c to 602f1d0 Compare September 26, 2021 19:44

tk0miya mentioned this pull request Sep 27, 2021

Intersphinx, refactoring and intersphinx_disable_domains #9459

Merged

hoefling force-pushed the crossrefcheck-builder branch from 4273745 to e03424f Compare October 20, 2021 21:10

hoefling mentioned this pull request Oct 30, 2021

Proposal: check if hardcoded URLs can be replaced with extlinks #9800

Merged

hoefling force-pushed the crossrefcheck-builder branch 2 times, most recently from 4026ad1 to f2f07a3 Compare November 12, 2021 19:18

hoefling changed the base branch from master to 4.x November 12, 2021 19:18

hoefling force-pushed the crossrefcheck-builder branch from f13bbb9 to 6dead54 Compare December 9, 2021 08:56

hoefling force-pushed the crossrefcheck-builder branch from aeafef9 to 48f8b2b Compare December 11, 2021 13:29

hoefling force-pushed the crossrefcheck-builder branch from 48f8b2b to 327f381 Compare December 20, 2021 13:08

jakobandersen added this to the 4.4.0 milestone Dec 29, 2021

tk0miya modified the milestones: 4.4.0, 4.5.0 Jan 15, 2022

hoefling mentioned this pull request Jan 17, 2022

Allow to bail out extlink replacement suggestion #10112

Closed

hoefling added 20 commits August 29, 2023 15:44

drop PEP 585-like type hints

eca5a24

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

drop PEP 585-like type hints for real this time, fix wrong module nam…

7c77805

…e in docstring Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

resort imports with isort

376a4fb

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

move the crossref check into intersphinx extension

6f6ff07

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

refactor initial suggestion, add tests

5071589

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

replace hardcoded refs in docs with crossrefs

556ae47

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

add changelog entry

6c08ff5

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

fix docslint

e155542

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

fix isort

af58453

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

apply suggestions from sphinx-doc#9800 here as well

06170a9

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

fix mypy

0312053

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

fix hardcoded refs to RTD docs

4e8dea5

Signed-off-by: Oleg Hoefling <oleg.hoefling@gmail.com>

lower checker priority to default one

d35df87

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

fix external crossrefs

1e28d5e

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

chore: invoke isort

b699ce6

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

chore: invoke ruff

de997b1

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

chore: invoke flake8

51c498f

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

chore: fix docutils warnings

5efab6f

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

chore: invoked isort

97c7853

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

chore: invoked ruff

2d50d64

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

hoefling force-pushed the crossrefcheck-builder branch from 9423340 to 2d50d64 Compare August 29, 2023 13:52

hoefling added 2 commits August 29, 2023 15:56

chore: fix broken type hints

ae2dc24

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

chore: fix duplicate imports

0e2ffb9

Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>

picnixz reviewed Aug 29, 2023

View reviewed changes

AA-Turner modified the milestones: 7.x, 8.x Jul 20, 2024

AA-Turner modified the milestones: 8.x, some future version Jan 12, 2025

AA-Turner force-pushed the master branch from 4447021 to d95dafa Compare February 16, 2025 02:56

Uh oh!

Conversation

hoefling commented Sep 11, 2021

Feature or Bugfix

Purpose

Usage

Caveats

Example output from running over Sphinx repository

Uh oh!

hoefling commented Sep 11, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tk0miya commented Sep 12, 2021

Uh oh!

jakobandersen commented Sep 12, 2021

Uh oh!

Zac-HD commented Sep 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hoefling commented Sep 25, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Zac-HD commented Sep 25, 2021

Uh oh!

RonnyPfannschmidt commented Sep 25, 2021

Uh oh!

hoefling commented Sep 26, 2021

Uh oh!

hoefling commented Dec 9, 2021

Uh oh!

hoefling commented Aug 29, 2023

Uh oh!

picnixz Aug 29, 2023

Choose a reason for hiding this comment

Uh oh!

picnixz Aug 29, 2023

Choose a reason for hiding this comment

Uh oh!

picnixz Aug 29, 2023

Choose a reason for hiding this comment

Uh oh!

picnixz Aug 29, 2023

Choose a reason for hiding this comment

Uh oh!

picnixz Aug 29, 2023

Choose a reason for hiding this comment

Uh oh!

picnixz Aug 29, 2023

Choose a reason for hiding this comment

Uh oh!

picnixz Aug 29, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Example output from running over `Sphinx` repository

hoefling commented Sep 11, 2021 •

edited

Loading

Zac-HD commented Sep 13, 2021 •

edited

Loading

hoefling commented Sep 25, 2021 •

edited

Loading

picnixz Aug 29, 2023 •

edited

Loading