Add docs showing pip-tools usage on dependencies

This will help users not have random jinja or docutils updates break their builds.

Fixes #9039

Author: ericholscher

docs/user/guides/reproducible-builds.rst

@@ -42,7 +42,7 @@ and **those settings live in your repository**.
 A configuration file with explicit dependencies looks like this:
 
 .. code-block:: yaml
-   
+
    # File: .readthedocs.yaml
 
    version: 2
@@ -85,7 +85,7 @@ for example:
    and its dependencies using a requirements file.
 
    .. code-block:: yaml
-      
+
       # File: .readthedocs.yaml
 
       version: 2
@@ -106,7 +106,7 @@ for example:
    Your project is relying on the default Python version and default installed dependencies.
 
    .. code-block:: yaml
-      
+
       # File: .readthedocs.yaml
 
       version: 2
@@ -134,7 +134,7 @@ Some examples:
       readthedocs-sphinx-search==0.1.1
 
    .. code-block:: yaml
-      
+
       # File: docs/environment.yaml
 
       name: docs
@@ -143,7 +143,7 @@ Some examples:
         - defaults
       dependencies:
         - sphinx==4.2.0
-        - nbsphinx==0.8.1 
+        - nbsphinx==0.8.1
         - pip:
           - sphinx_rtd_theme==1.0.0
 
@@ -160,7 +160,7 @@ Some examples:
       readthedocs-sphinx-search
 
    .. code-block:: yaml
-      
+
       # File: docs/environment.yaml
 
       name: docs
@@ -182,3 +182,89 @@ or our Conda docs about :ref:`environment files <guides/conda:creating the \`\`e
 
    Remember to update your docs' dependencies from time to time to get new improvements and fixes.
    It also makes it easy to manage in case a version reaches its end of support date.
+
+
+Pinning transitive dependencies
+-------------------------------
+
+Once you have pinned your own dependencies,
+the next thing to worry about are the additional dependencies of these projects.
+Transitive dependencies are these extra dependencies.
+
+We recommend `pip-tools`_ to help address this problem.
+It allows you to specify a ``requirements.in`` file with your first-level dependencies,
+and it generates a ``requirementes.txt`` file with the full set of transitive dependencies.
+
+.. _pip-tools: https://pip-tools.readthedocs.io/en/latest/
+
+✅ Good:
+    All your transitive dependencies will stay defined,
+    not allowing a package upgrade to break your docs.
+
+   .. code-block::
+
+      # File: docs/requirements.in
+
+      sphinx==4.2.0
+
+   .. code-block:: yaml
+
+      # File: docs/requirements.txt
+
+      # This file is autogenerated by pip-compile with python 3.7
+      # To update, run:
+      #
+      #    pip-compile docs.in
+      #
+      alabaster==0.7.12
+          # via sphinx
+      babel==2.10.1
+          # via sphinx
+      certifi==2021.10.8
+          # via requests
+      charset-normalizer==2.0.12
+          # via requests
+      docutils==0.17.1
+          # via sphinx
+      idna==3.3
+          # via requests
+      imagesize==1.3.0
+          # via sphinx
+      importlib-metadata==4.11.3
+          # via sphinx
+      jinja2==3.1.2
+          # via sphinx
+      markupsafe==2.1.1
+          # via jinja2
+      packaging==21.3
+          # via sphinx
+      pygments==2.11.2
+          # via sphinx
+      pyparsing==3.0.8
+          # via packaging
+      pytz==2022.1
+          # via babel
+      requests==2.27.1
+          # via sphinx
+      snowballstemmer==2.2.0
+          # via sphinx
+      sphinx==4.4.0
+          # via -r docs.in
+      sphinxcontrib-applehelp==1.0.2
+          # via sphinx
+      sphinxcontrib-devhelp==1.0.2
+          # via sphinx
+      sphinxcontrib-htmlhelp==2.0.0
+          # via sphinx
+      sphinxcontrib-jsmath==1.0.1
+          # via sphinx
+      sphinxcontrib-qthelp==1.0.3
+          # via sphinx
+      sphinxcontrib-serializinghtml==1.1.5
+          # via sphinx
+      typing-extensions==4.2.0
+          # via importlib-metadata
+      urllib3==1.26.9
+          # via requests
+      zipp==3.8.0
+          # via importlib-metadata