Merge pull request #9158 from readthedocs/pip-tools-docs

Add docs showing pip-tools usage on dependencies

Author: ericholscher

docs/user/guides/reproducible-builds.rst

@@ -42,8 +42,7 @@ and **those settings live in your repository**.
 A configuration file with explicit dependencies looks like this:
 
 .. code-block:: yaml
-   
-   # File: .readthedocs.yaml
+   :caption: .readthedocs.yaml
 
    version: 2
 
@@ -62,8 +61,7 @@ A configuration file with explicit dependencies looks like this:
        - requirements: docs/requirements.txt
 
 .. code-block::
-
-   # File: docs/requirements.txt
+   :caption: docs/requirements.txt
 
    # Defining the exact version will make sure things don't break
    sphinx==4.2.0
@@ -85,8 +83,7 @@ for example:
    and its dependencies using a requirements file.
 
    .. code-block:: yaml
-      
-      # File: .readthedocs.yaml
+      :caption: .readthedocs.yaml
 
       version: 2
 
@@ -106,8 +103,7 @@ for example:
    Your project is relying on the default Python version and default installed dependencies.
 
    .. code-block:: yaml
-      
-      # File: .readthedocs.yaml
+      :caption: .readthedocs.yaml
 
       version: 2
 
@@ -126,24 +122,22 @@ Some examples:
    in all platforms, and won't be updated unexpectedly.
 
    .. code-block::
-
-      # File: docs/requirements.txt
+      :caption: docs/requirements.txt
 
       sphinx==4.2.0
       sphinx_rtd_theme==1.0.0
       readthedocs-sphinx-search==0.1.1
 
    .. code-block:: yaml
-      
-      # File: docs/environment.yaml
+      :caption: docs/environment.yaml
 
       name: docs
       channels:
         - conda-forge
         - defaults
       dependencies:
         - sphinx==4.2.0
-        - nbsphinx==0.8.1 
+        - nbsphinx==0.8.1
         - pip:
           - sphinx_rtd_theme==1.0.0
 
@@ -152,16 +146,14 @@ Some examples:
    and your builds can fail or change unexpectedly any time.
 
    .. code-block::
-
-      # File: docs/requirements.txt
+      :caption: docs/requirements.txt
 
       sphinx
       sphinx_rtd_theme
       readthedocs-sphinx-search
 
    .. code-block:: yaml
-      
-      # File: docs/environment.yaml
+      :caption: docs/environment.yaml
 
       name: docs
       channels:
@@ -182,3 +174,88 @@ 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 things to worry about are the dependencies of your dependencies.
+These are called *transitive dependencies*,
+and they can upgrade without warning if you do not pin these packages as well.
+
+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 ``requirements.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,
+    which ensures new package releases will not break your docs.
+
+   .. code-block::
+      :caption: docs/requirements.in
+
+      sphinx==4.2.0
+
+   .. code-block:: yaml
+      :caption: 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