From 9af02e65408d0f62e73170eeb5d5a76adcdf4045 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 8 Mar 2021 12:49:58 -0500 Subject: [PATCH] Docs: guide about reproducible builds (#7888) Close https://github.com/readthedocs/readthedocs.org/issues/7852 Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/Makefile | 2 +- docs/builds.rst | 4 +- docs/faq.rst | 5 +- docs/guides/mkdocs-old-versions.rst | 3 +- docs/guides/platform.rst | 4 +- docs/guides/reproducible-builds.rst | 178 +++++++++++++++++++++ docs/guides/specifying-dependencies.rst | 48 ------ docs/intro/getting-started-with-mkdocs.rst | 3 +- docs/intro/getting-started-with-sphinx.rst | 2 +- docs/intro/import-guide.rst | 3 +- 10 files changed, 188 insertions(+), 64 deletions(-) create mode 100644 docs/guides/reproducible-builds.rst delete mode 100644 docs/guides/specifying-dependencies.rst diff --git a/docs/Makefile b/docs/Makefile index e05fbd3d276..3a1f013f62e 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -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." diff --git a/docs/builds.rst b/docs/builds.rst index f44879bac3d..36b298e43e7 100644 --- a/docs/builds.rst +++ b/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 `. + we recommend you :ref:`pinning the version ` 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 diff --git a/docs/faq.rst b/docs/faq.rst index bd2ea310198..018204a9778 100644 --- a/docs/faq.rst +++ b/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 `. - + by following this :ref:`guide `. Can I document a python package that is not at the root of my repository? ------------------------------------------------------------------------- diff --git a/docs/guides/mkdocs-old-versions.rst b/docs/guides/mkdocs-old-versions.rst index c3449f81d34..804de91da09 100644 --- a/docs/guides/mkdocs-old-versions.rst +++ b/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 `. - +More detailed information about how to specify dependencies can be found :ref:`here `. Upgrade your custom theme to be compatible with later MkDocs versions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/guides/platform.rst b/docs/guides/platform.rst index d51d7af6e17..737a79c157a 100644 --- a/docs/guides/platform.rst +++ b/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 diff --git a/docs/guides/reproducible-builds.rst b/docs/guides/reproducible-builds.rst new file mode 100644 index 00000000000..485ec1ec2a1 --- /dev/null +++ b/docs/guides/reproducible-builds.rst @@ -0,0 +1,178 @@ +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 +------------------ + +To test your build process, you can build them locally in a clean environment +(this is without any dependencies installed). +Then you should make sure you are running those same steps on Read the Docs. + +You can configure how your project is built from the web interface (:guilabel:`Admin` tab), +or by :ref:`using a configuration file ` (recommended). +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 ` **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 + + # Defining the exact version will make sure things don't break + sphinx==3.4.3 + sphinx_rtd_theme==0.5.1 + readthedocs-sphinx-search==0.1.0 + +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 `, +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 undefined 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 our Conda docs about :ref:`environment files `. + +.. _`pip user guide`: https://pip.pypa.io/en/stable/user_guide/#requirements-files + +.. tip:: + + 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. diff --git a/docs/guides/specifying-dependencies.rst b/docs/guides/specifying-dependencies.rst deleted file mode 100644 index 57e065ca75c..00000000000 --- a/docs/guides/specifying-dependencies.rst +++ /dev/null @@ -1,48 +0,0 @@ -Specifying Dependencies -======================= - -Any dependencies required for building a documentation project can be specified using a pip requirements file or a conda environment file. - -.. note:: For the purpose of building your documentation with RTD, *project* is the documentation project, and *project root* is the directory where all the documentation is stored, often named ``docs``. - -Specifying a requirements file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The requirements file option is useful for specifying dependencies required for building the documentation. -Additional uses specific to Read the Docs are mentioned at the end of this guide. - -For details about the purpose of pip requirements file and how to create one, check out `pip user guide`_. - -To use the requirements file, create and place the requirements file in the root directory of your documentation directory. -For example: - -.. code-block:: text - - # docs/requirements.txt - sphinx==3.2.1 - sphinx_rtd_theme==0.5.0 - -Using a configuration file --------------------------- - -The recommended approach for specifying a pip requirements file is to use a :doc:`/config-file/index` file, -see :ref:`config-file/v2:Requirements file`. - -Using the project admin dashboard ---------------------------------- - -Once the requirements file has been created; - -- Login to Read the Docs and go to the project admin dashboard. -- Go to **Admin > Advanced Settings > Requirements file**. -- Specify the path of the requirements file you just created. The path should be relative to the root directory of the documentation project. - -Using a conda environment file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If using conda, the dependencies can be specified in the `conda environment file`_: ``environment.yml`` . - -More on Read the Doc's conda support: :doc:`conda`. - -.. _`pip user guide`: https://pip.pypa.io/en/stable/user_guide/#requirements-files -.. _`conda environment file`: https://conda.io/docs/user-guide/tasks/manage-environments.html diff --git a/docs/intro/getting-started-with-mkdocs.rst b/docs/intro/getting-started-with-mkdocs.rst index ec3d369a3bf..bc688cc7666 100644 --- a/docs/intro/getting-started-with-mkdocs.rst +++ b/docs/intro/getting-started-with-mkdocs.rst @@ -66,10 +66,9 @@ you can start using Read the Docs by :doc:`importing your docs ` + We strongly recommend to :ref:`pin the MkDocs version ` used for your project to build the docs to avoid potential future incompatibilities. - External resources ------------------ diff --git a/docs/intro/getting-started-with-sphinx.rst b/docs/intro/getting-started-with-sphinx.rst index b51b89169c6..084f0cd40c0 100644 --- a/docs/intro/getting-started-with-sphinx.rst +++ b/docs/intro/getting-started-with-sphinx.rst @@ -83,7 +83,7 @@ by :doc:`importing your docs `. .. warning:: - We strongly recommend to :ref:`pin the Sphinx version ` + We strongly recommend to :ref:`pin the Sphinx version ` 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 diff --git a/docs/intro/import-guide.rst b/docs/intro/import-guide.rst index 9cbd244e485..0ded5ed3a29 100644 --- a/docs/intro/import-guide.rst +++ b/docs/intro/import-guide.rst @@ -76,8 +76,7 @@ You can configure these settings in a ``.readthedocs.yaml`` 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 `. +We recommend to set the version your project uses :ref:`explicitily `. 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.