diff --git a/docs/html/cli/pip.rst b/docs/html/cli/pip.rst
index 2c42174eab5..88ef33e1163 100644
--- a/docs/html/cli/pip.rst
+++ b/docs/html/cli/pip.rst
@@ -74,9 +74,8 @@ when decision is needed.
*(a)bort*
Abort pip and return non-zero exit status.
-
-Build System Interface
-======================
+.. _`2-build-system-interface`:
+.. rubric:: Build System Interface
This is now covered in :doc:`../reference/build-system/index`.
diff --git a/docs/html/cli/pip_install.rst b/docs/html/cli/pip_install.rst
index cfff4f7e270..408ef25ff96 100644
--- a/docs/html/cli/pip_install.rst
+++ b/docs/html/cli/pip_install.rst
@@ -148,19 +148,18 @@ profile:
3. For whatever reason, they don't or won't declare their build dependencies using
``setup_requires``.
-
-Requirements File Format
-------------------------
+.. _`0-requirements-file-format`:
+.. rubric:: Requirements File Format
This section has been moved to :doc:`../reference/requirements-file-format`.
-Requirement Specifiers
-----------------------
+.. _`0-requirement-specifiers`:
+.. rubric:: Requirement Specifiers
This section has been moved to :doc:`../reference/requirement-specifiers`.
-Per-requirement Overrides
--------------------------
+.. _`0-per-requirement-overrides`:
+.. rubric:: Per-requirement Overrides
This is now covered in :doc:`../reference/requirements-file-format`.
@@ -183,11 +182,8 @@ that enables installation of pre-releases and development releases.
.. _pre-releases: https://www.python.org/dev/peps/pep-0440/#handling-of-pre-releases
-
-.. _`VCS Support`:
-
-VCS Support
------------
+.. _`0-vcs-support`:
+.. rubric:: VCS Support
This is now covered in :doc:`../topics/vcs-support`.
@@ -224,45 +220,38 @@ store. The default bundled CA certificate store certificate store may be
overridden by using ``--cert`` option or by using ``PIP_CERT``,
``REQUESTS_CA_BUNDLE``, or ``CURL_CA_BUNDLE`` environment variables.
-
-.. _`Caching`:
-
-Caching
--------
+.. _`0-caching`:
+.. rubric:: Caching
This is now covered in :doc:`../topics/caching`.
-.. _`Wheel cache`:
-
-Wheel Cache
-^^^^^^^^^^^
+.. _`0-wheel-cache`:
+.. rubric:: Wheel Cache
This is now covered in :doc:`../topics/caching`.
-Hash checking mode
-------------------
+.. _`0-hash-checking-mode`:
+.. rubric:: Hash checking mode
This is now covered in :doc:`../topics/secure-installs`.
-Local Project Installs
-----------------------
+.. _`0-local-project-installs`:
+.. rubric:: Local Project Installs
This is now covered in :doc:`../topics/local-project-installs`.
-Editable installs
------------------
+.. _`0-editable-installs`:
+.. rubric:: Editable installs
This is now covered in :doc:`../topics/local-project-installs`.
-Build System Interface
-----------------------
+.. _`0-build-system-interface`:
+.. rubric:: Build System Interface
This is now covered in :doc:`../reference/build-system/index`.
-
.. _`pip install Options`:
-
Options
=======
diff --git a/docs/html/cli/pip_wheel.rst b/docs/html/cli/pip_wheel.rst
index bf371f28506..153d6925d4e 100644
--- a/docs/html/cli/pip_wheel.rst
+++ b/docs/html/cli/pip_wheel.rst
@@ -25,8 +25,8 @@ Description
.. pip-command-description:: wheel
-Build System Interface
-----------------------
+.. _`1-build-system-interface`:
+.. rubric:: Build System Interface
This is now covered in :doc:`../reference/build-system/index`.
diff --git a/docs/html/topics/configuration.md b/docs/html/topics/configuration.md
index 700a4d0ebf2..9b240ec7902 100644
--- a/docs/html/topics/configuration.md
+++ b/docs/html/topics/configuration.md
@@ -1,3 +1,5 @@
+(configuration)=
+
# Configuration
pip allows a user to change its behaviour via 3 mechanisms:
@@ -9,6 +11,8 @@ pip allows a user to change its behaviour via 3 mechanisms:
This page explains how the configuration files and environment variables work,
and how they are related to pip's various command line options.
+(config-file)=
+
## Configuration Files
Configuration files can change the default values for command line option.
@@ -84,6 +88,8 @@ a configuration file that's loaded first, and whose values are overridden by
the values set in the aforementioned files. Setting this to {any}`os.devnull`
disables the loading of _all_ configuration files.
+(config-precedence)=
+
### Loading order
When multiple configuration files are found, pip combines them in the following
diff --git a/docs/html/topics/dependency-resolution.md b/docs/html/topics/dependency-resolution.md
index 7dd9848b021..6d02866a7ef 100644
--- a/docs/html/topics/dependency-resolution.md
+++ b/docs/html/topics/dependency-resolution.md
@@ -161,6 +161,8 @@ with [pip-tools](https://github.com/jazzband/pip-tools/).
This means the "work" is done once during development process, and thus
will avoid performing dependency resolution during deployment.
+(Fixing conflicting dependencies)=
+
## Dealing with dependency conflicts
This section provides practical suggestions to pip users who encounter
diff --git a/docs/html/topics/vcs-support.md b/docs/html/topics/vcs-support.md
index d42c5c92e40..538b4a7912d 100644
--- a/docs/html/topics/vcs-support.md
+++ b/docs/html/topics/vcs-support.md
@@ -1,3 +1,4 @@
+(vcs support)=
# VCS Support
pip supports installing from various version control systems (VCS).
diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst
index 6a25a6e6ae3..988c94a3f68 100644
--- a/docs/html/user_guide.rst
+++ b/docs/html/user_guide.rst
@@ -59,19 +59,18 @@ For more information and examples, see the :ref:`pip install` reference.
.. _PyPI: https://pypi.org/
-
-Basic Authentication Credentials
-================================
+.. _`0-basic-authentication-credentials`:
+.. rubric:: Basic Authentication Credentials
This is now covered in :doc:`topics/authentication`.
-netrc Support
--------------
+.. _`0-netrc-support`:
+.. rubric:: netrc Support
This is now covered in :doc:`topics/authentication`.
-Keyring Support
----------------
+.. _`0-keyring-support`:
+.. rubric:: Keyring Support
This is now covered in :doc:`topics/authentication`.
@@ -451,34 +450,26 @@ packages.
For more information and examples, see the :ref:`pip search` reference.
-.. _`Configuration`:
-
-
-Configuration
-=============
+.. _`0-configuration`:
+.. rubric:: Configuration
This is now covered in :doc:`topics/configuration`.
-.. _config-file:
-
-Config file
------------
+.. _`0-config-file`:
+.. rubric:: Config file
This is now covered in :doc:`topics/configuration`.
-Environment Variables
----------------------
+.. _`0-environment-variables`:
+.. rubric:: Environment Variables
This is now covered in :doc:`topics/configuration`.
-.. _config-precedence:
-
-Config Precedence
------------------
+.. _`0-config-precedence`:
+.. rubric:: Config Precedence
This is now covered in :doc:`topics/configuration`.
-
Command Completion
==================
@@ -780,18 +771,14 @@ is the latest version:
[...]
Successfully installed SomePackage
-.. _`Repeatability`:
-
-
-Ensuring Repeatability
-======================
+.. _`0-repeatability`:
+.. _`0-ensuring-repeatability`:
+.. rubric:: Ensuring Repeatability
This is now covered in :doc:`../topics/repeatable-installs`.
-.. _`Fixing conflicting dependencies`:
-
-Fixing conflicting dependencies
-===============================
+.. _`0-fixing-conflicting-dependencies`:
+.. rubric:: Fixing conflicting dependencies
This is now covered in :doc:`../topics/dependency-resolution`.