Docs: guide about reproducible builds

Close #7852

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -W
+SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
@@ -53,7 +53,7 @@ clean:
 	rm -rf $(BUILDDIR)/*
 
 auto:
-	sphinx-autobuild -p 8888 $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	sphinx-autobuild --port 8888 $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
@@ -63,7 +63,7 @@ html:
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 livehtml:
-	sphinx-autobuild -p 4444 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	sphinx-autobuild --port 4444 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
 
 dirhtml:

docs/builds.rst

@@ -67,9 +67,7 @@ An example in code:
 .. note::
 
     Regardless of whether you build your docs with Sphinx or MkDocs,
-    we recommend you pin the version of Sphinx or Mkdocs you want us to use.
-    You can do this the same way other
-    :doc:`dependencies are specified <guides/specifying-dependencies>`.
+    we recommend you :ref:`pinning the version <guides/reproducible-builds:pinning dependencies>` of Sphinx or Mkdocs you want us to use.
     Some examples of pinning versions might be ``sphinx<2.0`` or ``mkdocs>=1.0``.
 
 Build environment

docs/faq.rst

@@ -33,7 +33,7 @@ My documentation requires additional dependencies
 -------------------------------------------------
 
 For most Python dependencies, you can can specify a requirements file
-which details your dependencies. See our guide on :doc:`/guides/specifying-dependencies`.
+which details your dependencies. See our guide on :ref:`guides/reproducible-builds:using a configuration file`.
 You can also set your project documentation to install your project itself
 as a dependency.
 
@@ -216,8 +216,7 @@ and as a result, it tends to look a bit better with the default theme.
 .. note::
 
    To use these extensions you need to specify the dependencies on your project
-   by following this :doc:`guide <guides/specifying-dependencies>`.
-
+   by following this :ref:`guide <guides/reproducible-builds:using a configuration file>`.
 
 Can I document a python package that is not at the root of my repository?
 -------------------------------------------------------------------------

docs/guides/mkdocs-old-versions.rst

@@ -29,8 +29,7 @@ To make your project continue using this version you will need to create a ``req
      markdown>=2.3.1,<2.5
 
 
-More detailed information about how to specify dependencies can be found :ref:`here <guides/specifying-dependencies:Specifying Dependencies>`.
-
+More detailed information about how to specify dependencies can be found :ref:`here <guides/reproducible-builds:pinning dependencies>`.
 
 Upgrade your custom theme to be compatible with later MkDocs versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/guides/platform.rst

@@ -11,12 +11,12 @@ These guides will help you customize or tune aspects of Read the Docs.
    canonical
    conda
    deprecating-content
+   embedding-content
    environment-variables
    feature-flags
    google-analytics
    hiding-a-version
+   reproducible-builds
    searching-with-readthedocs
-   embedding-content
-   specifying-dependencies
    technical-docs-seo-guide
    wipe-environment

docs/guides/reproducible-builds.rst

@@ -0,0 +1,179 @@
+Reproducible Builds
+===================
+
+Your docs depend on tools and other dependencies to be built.
+If your docs don't have reproducible builds,
+an update in a dependency can break your builds when least expected,
+or make your docs look different from your local version.
+This guide will help you to keep your builds working over time, and in a reproducible way.
+
+.. contents:: Contents
+   :local:
+   :depth: 3
+
+Building your docs
+------------------
+
+A way to know the build process of your docs is by building them locally in a clean environment
+(this is without any dependencies installed),
+and making sure you are replicating those same steps on Read the Docs.
+
+You can configure how your project is build from the web interface (:guilabel:`Admin` tab),
+or by :ref:`using a configuration file <guides/reproducible-builds:using a configuration file>`.
+If you aren't familiar with these tools, check our docs:
+
+- :doc:`/intro/getting-started-with-sphinx`
+- :doc:`/intro/getting-started-with-mkdocs`
+- :doc:`/config-file/v2`
+
+.. note::
+
+   You can see the exact commands that are run on Read the Docs by going to the :guilabel:`Builds` tab of your project.
+
+Using a configuration file
+--------------------------
+
+If you use the web interface to configure your project,
+the options are applied to *all* versions and builds of your docs,
+and can be lost after changing them over time.
+Using a :doc:`configuration file </config-file/v2>` **provides you per version settings**,
+and **those settings live in your repository**.
+
+A configuration file with explicit dependencies looks like this:
+
+.. code-block:: yaml
+   
+   # File: readthedocs.yaml
+
+   version: 2
+
+   # Build from the docs/ directory with Sphinx
+   sphinx:
+     configuration: docs/conf.py
+
+   # Explicitly set the version of Python and its requirements
+   python:
+     version: 3.7
+     install:
+       - requirements: docs/requirements.txt
+
+.. code-block::
+
+   # File: docs/requirements.txt
+
+   # Explicitly dependencies and versions
+   sphinx==3.4.3
+   sphinx_rtd_theme==0.5.1
+   readthedocs-sphinx-search==0.1.0rc3
+
+Don't rely on implicit dependencies
+-----------------------------------
+
+By default Read the Docs will install the tool you chose to build your docs,
+and other dependencies, this is done so new users can build their docs without much configuration.
+
+We highly recommend not to assume these dependencies will always be present or that their versions won't change.
+Always declare your dependencies explicitly using a :ref:`configuration file <guides/reproducible-builds:using a configuration file>`,
+for example:
+
+✅ Good:
+   Your project is declaring the Python version explicitly,
+   and its dependencies using a requirements file.
+
+   .. code-block:: yaml
+      
+      # File: .readthedocs.yaml
+
+      version: 2
+
+      sphinx:
+        configuration: docs/conf.py
+
+      python:
+        version: 3.7
+        install:
+          - requirements: docs/requirements.txt
+
+❌ Bad:
+   Your project is relying on the default Python version and default installed dependencies.
+
+   .. code-block:: yaml
+      
+      # File: .readthedocs.yaml
+
+      version: 2
+
+      sphinx:
+         configuration: docs/conf.py
+
+Pinning dependencies
+--------------------
+
+As you shouldn't rely on implicit dependencies,
+you shouldn't rely on arbitrary versions of your dependencies.
+Some examples:
+
+✅ Good:
+   The specified versions will be used for all your builds,
+   in all platforms, and won't be updated unexpectedly.
+
+   .. code-block::
+
+      # File: docs/requirements.txt
+
+      sphinx==3.4.3
+      sphinx_rtd_theme==0.5.1
+      readthedocs-sphinx-search==0.1.0rc3
+
+   .. code-block:: yaml
+      
+      # File: docs/environment.yaml
+
+      name: docs
+      channels:
+        - conda-forge
+        - defaults
+      dependencies:
+        - sphinx==3.4.3
+        - nbsphinx==0.8.1 
+        - pip:
+          - sphinx_rtd_theme==0.5.1
+
+❌ Bad:
+   The latest or any other already installed version will be used,
+   and your builds can fail or change unexpectedly any time.
+
+   .. code-block::
+
+      # File: docs/requirements.txt
+
+      sphinx
+      sphinx_rtd_theme
+      readthedocs-sphinx-search
+
+   .. code-block:: yaml
+      
+      # File: docs/environment.yaml
+
+      name: docs
+      channels:
+        - conda-forge
+        - defaults
+      dependencies:
+        - sphinx
+        - nbsphinx
+        - pip:
+          - sphinx_rtd_theme
+
+Check the `pip user guide`_ for more information about requirements files,
+or the Conda docs about `environment files`_.
+
+.. _`pip user guide`: https://pip.pypa.io/en/stable/user_guide/#requirements-files
+.. _`environment files`: https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html
+
+.. note::
+
+   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 it's end of support date.
+
+   .. TODO: link to the supported versions policy.

docs/intro/getting-started-with-mkdocs.rst

@@ -66,10 +66,9 @@ you can start using Read the Docs by :doc:`importing your docs </intro/import-gu
 
 .. warning::
 
-   We strongly recommend to :ref:`pin the MkDocs version <guides/specifying-dependencies:Specifying Dependencies>`
+   We strongly recommend to :ref:`pin the MkDocs version <guides/reproducible-builds:pinning dependencies>`
    used for your project to build the docs to avoid potential future incompatibilities.
 
-
 External resources
 ------------------
 

docs/intro/getting-started-with-sphinx.rst

@@ -83,7 +83,7 @@ by :doc:`importing your docs </intro/import-guide>`.
 
 .. warning::
 
-   We strongly recommend to :ref:`pin the Sphinx version <guides/specifying-dependencies:Specifying Dependencies>`
+   We strongly recommend to :ref:`pin the Sphinx version <guides/reproducible-builds:pinning dependencies>`
    used for your project to build the docs to avoid potential future incompatibilities.
 
 .. _this template: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#id1

docs/intro/import-guide.rst

@@ -76,8 +76,7 @@ You can configure these settings in a ``readthedocs.yml`` file.
 See our :doc:`/config-file/index` docs for more details.
 
 It is also important to note that the default version of Sphinx is ``v1.8.5``.
-If choosing to build your documentation other than this,
-:ref:`it must be specified <guides/specifying-dependencies:Specifying Dependencies>`.
+We recommend to set the version your project uses :ref:`explicitily <guides/reproducible-builds:don't rely on implicit dependencies>`.
 
 Read the Docs will host multiple versions of your code. You can read more about
 how to use this well on our :doc:`/versions` page.