mirror of
https://github.com/django/django.git
synced 2024-12-23 01:25:58 +00:00
Fixed #32720 -- Added configuration and docs for Sphinx link checker.
We explicitly ignore checking anchors for line-range anchors on GitHub which are dynamically generated and, otherwise, show up as broken links. See https://github.com/sphinx-doc/sphinx/issues/7388#issuecomment-739961689. We also ignore links to resources that require authentication.
This commit is contained in:
parent
c156e36955
commit
0851933cba
22
docs/conf.py
22
docs/conf.py
@ -50,6 +50,28 @@ extensions = [
|
||||
autosectionlabel_prefix_document = True
|
||||
autosectionlabel_maxdepth = 2
|
||||
|
||||
# Linkcheck settings.
|
||||
linkcheck_ignore = [
|
||||
# Special-use addresses and domain names. (RFC 6761/6890)
|
||||
r'^https?://(?:127\.0\.0\.1|\[::1\])(?::\d+)?/',
|
||||
r'^https?://(?:[^/\.]+\.)*example\.(?:com|net|org)(?::\d+)?/',
|
||||
r'^https?://(?:[^/\.]+\.)*(?:example|invalid|localhost|test)(?::\d+)?/',
|
||||
# Pages that are inaccessible because they require authentication.
|
||||
r'^https://github\.com/[^/]+/[^/]+/fork',
|
||||
r'^https://code\.djangoproject\.com/github/login',
|
||||
r'^https://code\.djangoproject\.com/newticket',
|
||||
r'^https://(?:code|www)\.djangoproject\.com/admin/',
|
||||
r'^https://www\.djangoproject\.com/community/add/blogs/',
|
||||
r'^https://www\.google\.com/webmasters/tools/ping',
|
||||
r'^https://search\.google\.com/search-console/welcome',
|
||||
# Fragments used to dynamically switch content or populate fields.
|
||||
r'^https://webchat\.freenode\.net/#',
|
||||
r'^https://github\.com/[^#]+#L\d+-L\d+$',
|
||||
r'^https://help\.apple\.com/itc/podcasts_connect/#/itc',
|
||||
# Anchors on certain pages with missing a[name] attributes.
|
||||
r'^https://tools\.ietf\.org/html/rfc1123\.html#section-',
|
||||
]
|
||||
|
||||
# Spelling check needs an additional module that is not installed by default.
|
||||
# Add it only if spelling check is requested so docs can be generated without it.
|
||||
if 'spelling' in sys.argv:
|
||||
|
@ -510,6 +510,28 @@ one of the following:
|
||||
* If, and only if, you are sure the word you are using is correct - add it
|
||||
to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).
|
||||
|
||||
.. _documentation-link-check:
|
||||
|
||||
Link check
|
||||
==========
|
||||
|
||||
Links in documentation can become broken or changed such that they are no
|
||||
longer the canonical link. Sphinx provides a builder that can check whether the
|
||||
links in the documentation are working. From the ``docs`` directory, run ``make
|
||||
linkcheck``. Output is printed to the terminal, but can also be found in
|
||||
``_build/linkcheck/output.txt`` and ``_build/linkcheck/output.json``.
|
||||
|
||||
Entries that have a status of "working" are fine, those that are "unchecked" or
|
||||
"ignored" have been skipped because they either cannot be checked or have
|
||||
matched ignore rules in the configuration.
|
||||
|
||||
Entries that have a status of "broken" need to be fixed. Those that have a
|
||||
status of "redirected" may need to be updated to point to the canonical
|
||||
location, e.g. the scheme has changed ``http://`` → ``https://``. In certain
|
||||
cases, we do not want to update a "redirected" link, e.g. a rewrite to always
|
||||
point to the latest or stable version of documentation, e.g. ``/en/stable/`` →
|
||||
``/en/3.2/``.
|
||||
|
||||
Translating documentation
|
||||
=========================
|
||||
|
||||
|
@ -103,9 +103,9 @@ any time leading up to the actual release:
|
||||
#. Check with the other committers to make sure they don't have any
|
||||
uncommitted changes for the release.
|
||||
|
||||
#. Proofread the release notes, including looking at the online
|
||||
version to catch any broken links or reST errors, and make sure the
|
||||
release notes contain the correct date.
|
||||
#. Proofread the release notes, including looking at the online version to
|
||||
:ref:`catch any broken links <documentation-link-check>` or reST errors, and
|
||||
make sure the release notes contain the correct date.
|
||||
|
||||
#. Double-check that the release notes mention deprecation timelines
|
||||
for any APIs noted as deprecated, and that they mention any changes
|
||||
|
Loading…
Reference in New Issue
Block a user