[doc] cleanup references and update external URLs (#12182)

Author: picnixz

.flake8

@@ -32,5 +32,6 @@ exclude =
     sphinx/search/*,
     doc/usage/extensions/example*.py,
 per-file-ignores =
+    doc/conf.py:W605
     tests/test_extensions/ext_napoleon_pep526_data_google.py:MLL001,
     tests/test_extensions/ext_napoleon_pep526_data_numpy.py:MLL001,

.ruff.toml

@@ -367,7 +367,7 @@ select = [
 "doc/*" = [
     "ANN",  # documentation doesn't need annotations
 ]
-"doc/conf.py" = ["INP001"]
+"doc/conf.py" = ["INP001", "W605"]
 "doc/development/tutorials/examples/*" = ["INP001"]
 # allow print() in the tutorial
 "doc/development/tutorials/examples/recipe.py" = ["T201"]

CHANGES.rst

@@ -36,10 +36,11 @@ Features added
 * #12131: Added :confval:`show_warning_types` configuration option.
   Patch by Chris Sewell.
 
-* #11701: HTML Search: Adopt the new `<search>`_ element.
+* #11701: HTML Search: Adopt the new `\<search\>`_ element.
   Patch by Bénédikt Tran.
 
-  .. _`<search>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/search
+  .. _`\<search\>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/search
+
 * #11803: autodoc: Use an overriden ``__repr__()`` function in an enum,
   if defined. Patch by Shengyu Zhang.
 

EXAMPLES.rst

@@ -60,7 +60,6 @@ Documentation using the classic theme
 * `Buildbot <https://docs.buildbot.net/latest/>`__
 * `CMake <https://cmake.org/documentation/>`__ (customized)
 * `Chaco <https://docs.enthought.com/chaco/>`__ (customized)
-* `Cormoran <https://cormoran.nhopkg.org/docs/>`__
 * `DEAP <https://deap.readthedocs.io/>`__ (customized)
 * `Director <https://pythonhosted.org/director/>`__
 * `EZ-Draw <https://pageperso.lis-lab.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html>`__ (customized)
@@ -71,7 +70,7 @@ Documentation using the classic theme
 * `Grok <https://web.archive.org/web/20230708190705/http://grok.zope.org/doc/current/>`__ (customized)
 * `GROMACS <https://manual.gromacs.org/documentation/>`__
 * `GSL Shell <https://www.nongnu.org/gsl-shell/>`__
-* `Hands-on Python Tutorial <https://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/>`__
+* `Hands-on Python Tutorial <http://anh.cs.luc.edu:80/python/hands-on/3.1/handsonHtml/>`__
 * `Kaa <https://freevo.github.io/kaa-base/>`__ (customized)
 * `Leo <https://leoeditor.com/>`__ (customized)
 * `Mayavi <https://docs.enthought.com/mayavi/mayavi/>`__ (customized)
@@ -116,7 +115,7 @@ Documentation using the sphinxdoc theme
 * `Pyre <https://pyre.readthedocs.io/>`__
 * `pySPACE <https://pyspace.github.io/pyspace/>`__
 * `Pysparse <https://pysparse.sourceforge.net/>`__
-* `PyTango <https://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/>`__
+* `PyTango <https://pytango.readthedocs.io>`__
 * `Python Wild Magic <https://vmlaker.github.io/pythonwildmagic/>`__ (customized)
 * `RDKit <https://www.rdkit.org/docs/>`__
 * `Reteisi <https://www.reteisi.org/contents.html>`__ (customized)
@@ -186,7 +185,6 @@ Documentation using sphinx_rtd_theme
 * `dj-stripe <https://dj-stripe.readthedocs.io/>`__
 * `edX <https://docs.edx.org/>`__
 * `Electrum <https://docs.electrum.org/>`__
-* `Elemental <https://libelemental.org/documentation/dev/>`__
 * `ESWP3 <https://eswp3.readthedocs.io/>`__
 * `Ethereum Homestead <https://www.ethdocs.org/>`__
 * `Exhale <https://exhale.readthedocs.io/>`__
@@ -205,7 +203,6 @@ Documentation using sphinx_rtd_theme
 * `HDF5 for Python (h5py) <https://docs.h5py.org/>`__
 * `HyperKitty <https://hyperkitty.readthedocs.io/>`__
 * `Hyperledger Fabric <https://hyperledger-fabric.readthedocs.io/>`__
-* `Hyperledger Sawtooth <https://sawtooth.hyperledger.org/docs/>`__
 * `IdentityServer <https://docs.identityserver.io/>`__
 * `Idris <https://docs.idris-lang.org/>`__
 * `Inkscape <https://inkscape-manuals.readthedocs.io/>`__ (customized)
@@ -266,6 +263,7 @@ Documentation using sphinx_rtd_theme
 * `Qtile <https://docs.qtile.org/>`__
 * `Quex <https://quex.sourceforge.net/doc/html/main.html>`__
 * `QuTiP <https://qutip.org/docs/latest/>`__
+* `Sawtooth <https://sawtooth.splinter.dev/docs>`__
 * `Scapy <https://scapy.readthedocs.io/>`__
 * `SimGrid <https://simgrid.org/doc/latest/>`__
 * `SimPy <https://simpy.readthedocs.io/>`__
@@ -418,11 +416,9 @@ Homepages and other non-documentation sites
 * `Institute for the Design of Advanced Energy Systems (IDAES) <https://idaes-pse.readthedocs.io/>`__ (sphinx_rtd_theme)
 * `IDAES Examples <https://idaes.github.io/examples-pse/>`__ (sphinx_rtd_theme)
 * `Lei Ma's Statistical Mechanics lecture notes <https://statisticalphysics.leima.is/>`__ (sphinx_bootstrap_theme)
-* `Loyola University Chicago CS Academic Programs <https://academics.cs.luc.edu/index.html>`__ (sphinx_rtd_theme, customized)
 * `PyXLL <https://www.pyxll.com/>`__ (sphinx_bootstrap_theme, customized)
 * `SciPy Cookbook <https://scipy-cookbook.readthedocs.io/>`__ (sphinx_rtd_theme)
 * `Tech writer at work blog <https://documatt.com/blog/>`__ (custom theme)
-* `Thomas Cokelaer's Python, Sphinx and reStructuredText tutorials <https://thomas-cokelaer.info/tutorials/>`__ (standard)
 * `UC Berkeley ME233 Advanced Control Systems II course <https://berkeley-me233.github.io/>`__ (sphinxdoc)
 * `Željko Svedružić's Biomolecular Structure and Function Laboratory (BioSFLab) <https://svedruziclab.github.io/>`__ (sphinx_bootstrap_theme)
 

Makefile

@@ -45,8 +45,8 @@ clean: clean
 
 .PHONY: style-check
 style-check:
-	@flake8 .
-	@ruff check .
+	@echo '[+] running flake8' ; flake8 .
+	@echo '[+] running ruff' ; ruff check .
 
 .PHONY: format
 format:

doc/changes.rst

@@ -1,7 +1,5 @@
 :tocdepth: 1
 
-.. default-role:: any
-
 .. _changes:
 
 =========

doc/conf.py

@@ -101,11 +101,22 @@
 latex_use_xindy = True
 
 linkcheck_timeout = 5
+linkcheck_ignore = [
+    r'^contents\.html$',  # extra generated page
+    '^\.\./contents\.html$',
+    re.escape('https://gitlab.com/projects/new'),  # requires sign-in
+    re.escape('https://web.libera.chat/?channel=#sphinx-doc'),
+]
+linkcheck_anchors_ignore_for_url = [
+    # anchors in Markdown files cannot be accessed directly
+    'https://github.com/Khan/style-guides/blob/master/style/python.md',
+]
 
 autodoc_member_order = 'groupwise'
 autosummary_generate = False
 todo_include_todos = True
 extlinks = {
+    'dupage': ('https://docutils.sourceforge.io/docs/ref/rst/' '%s.html', '%s'),
     'duref': (
         'https://docutils.sourceforge.io/docs/ref/rst/' 'restructuredtext.html#%s',
         '%s',

doc/development/builders.rst

@@ -25,4 +25,4 @@ for 'mybuilder' can be defined in the extension's ``pyproject.toml``
 Note that it is still necessary to register the builder using
 :meth:`~.Sphinx.add_builder` in the extension's :func:`setup` function.
 
-.. _entry points: https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins
+.. _entry points: https://setuptools.pypa.io/en/latest/userguide/entry_point.html

doc/tutorial/deploying.rst

@@ -109,16 +109,11 @@ The quickest way to upload an existing project to GitHub is to:
    sources, complicating your workflow.
 
 These steps do not require access to the command line or installing any
-additional software. To learn more, you can:
+additional software. To learn more, read `this quickstart tutorial`_ or
+consult the `official GitHub documentation`_
 
-- Follow `this interactive GitHub course`_ to learn more about how the GitHub
-  interface works.
-- Read `this quickstart tutorial`_ to install extra software on your machine
-  and have more flexibility. You can either use the Git command line, or the
-  GitHub Desktop application.
-
-.. _this interactive GitHub course: https://lab.github.com/githubtraining/introduction-to-github
 .. _this quickstart tutorial: https://docs.github.com/en/get-started/quickstart
+.. _official GitHub documentation: https://docs.github.com/en/get-started
 
 GitLab
 ~~~~~~

doc/usage/extensions/autodoc.rst

@@ -40,7 +40,7 @@ you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension.
 :mod:`napoleon <sphinx.ext.napoleon>` is a preprocessor that converts your
 docstrings to correct reStructuredText before :mod:`autodoc` processes them.
 
-.. _Google: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
+.. _Google: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
 .. _NumPy: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
 
 

doc/usage/installation.rst

@@ -64,7 +64,7 @@ a Python distribution such as `Anaconda`__.
 
 __ https://brew.sh/
 __ https://www.macports.org/
-__ https://www.anaconda.com/download/#macos
+__ https://www.anaconda.com/download
 
 Homebrew
 ~~~~~~~~
@@ -199,9 +199,7 @@ use the following command.
 
    $ python -m venv .venv
 
-You can read more about them in the `Python Packaging User Guide`_.
-
-.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
+.. seealso:: :mod:`venv` -- creating virtual environments
 
 .. warning::
 

doc/usage/restructuredtext/basics.rst

@@ -289,7 +289,7 @@ information.
 Roles
 -----
 
-A role or "custom interpreted text role" (:duref:`ref <roles>`) is an inline
+A role or "custom interpreted text role" (:dupage:`ref <roles>`) is an inline
 piece of explicit markup. It signifies that the enclosed text should be
 interpreted in a specific way.  Sphinx uses this to provide semantic markup and
 cross-referencing of identifiers, as described in the appropriate section.  The