Docs: update versions on config file page (#9838)

* Docs: update versions on config file page - Update all the versions used in the examples to the latest ones supported by Read the Docs. - Remove deprecated keys from examples, like `python.version: "3.7"` This way we avoid new users copy and pasting examples with outdated versions. * Update versions in reproducible-builds.rst * Update docs/user/config-file/v2.rst Co-authored-by: Benjamin Balder Bach <[email protected]> * Apply suggestions from code review Co-authored-by: Benjamin Bach <[email protected]> Co-authored-by: Benjamin Balder Bach <[email protected]>
readthedocs · Dec 22, 2022 · c4a15c8 · c4a15c8
1 parent 2d68f18
commit c4a15c8
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 51 deletions.
diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst
@@ -23,13 +23,13 @@ Below is an example YAML file which shows the most common configuration options:
 
          # Set the version of Python and other tools you might need
          build:
-           os: ubuntu-20.04
+           os: ubuntu-22.04
            tools:
-             python: "3.9"
+             python: "3.11"
              # You can also specify other tool versions:
-             # nodejs: "16"
-             # rust: "1.55"
-             # golang: "1.17"
+             # nodejs: "19"
+             # rust: "1.64"
+             # golang: "1.19"
 
          # Build documentation in the docs/ directory with Sphinx
          sphinx:
@@ -57,9 +57,9 @@ Below is an example YAML file which shows the most common configuration options:
 
          # Set the version of Python and other tools you might need
          build:
-           os: ubuntu-20.04
+           os: ubuntu-22.04
            tools:
-             python: "3.9"
+             python: "3.11"
 
          mkdocs:
            configuration: mkdocs.yml
@@ -201,7 +201,6 @@ Example:
    version: 2
 
    python:
-     version: "3.7"
      install:
        - requirements: docs/requirements.txt
        - requirements: requirements.txt
@@ -249,7 +248,6 @@ Example:
    version: 2
 
    python:
-     version: "3.7"
      install:
        - method: pip
          path: .
@@ -313,12 +311,12 @@ Python, Node.js, Rust, and Go.
    version: 2
 
    build:
-     os: ubuntu-20.04
+     os: ubuntu-22.04
      tools:
-       python: "3.9"
-       nodejs: "16"
-       rust: "1.55"
-       golang: "1.17"
+       python: "3.11"
+       nodejs: "18"
+       rust: "1.64"
+       golang: "1.19"
 
 build.os
 ````````
@@ -381,6 +379,7 @@ Node.js version to use.
    - ``14``
    - ``16``
    - ``18``
+   - ``19``
 
 build.tools.rust
 ````````````````
@@ -391,6 +390,7 @@ Rust version to use.
 :Options:
    - ``1.55``
    - ``1.61``
+   - ``1.64``
 
 build.tools.golang
 ``````````````````
@@ -401,6 +401,7 @@ Go version to use.
 :Options:
    - ``1.17``
    - ``1.18``
+   - ``1.19``
 
 build.apt_packages
 ``````````````````
@@ -444,7 +445,7 @@ See :doc:`/build-customization` for more details.
    build:
      os: ubuntu-22.04
      tools:
-       python: "3.10"
+       python: "3.11"
      jobs:
        pre_create_environment:
          - echo "Command run at 'pre_create_environment' step"
@@ -489,7 +490,7 @@ The ``_readthedocs/html`` directory (relative to the checkout's path) will be up
    build:
      os: ubuntu-22.04
      tools:
-       python: "3.10"
+       python: "3.11"
      commands:
        - pip install pelican
        - pelican --settings docs/pelicanconf.py --output _readthedocs/html/ docs/

diff --git a/docs/user/guides/reproducible-builds.rst b/docs/user/guides/reproducible-builds.rst
@@ -47,9 +47,9 @@ A configuration file with explicit dependencies looks like this:
    version: 2
 
    build:
-     os: "ubuntu-20.04"
+     os: "ubuntu-22.04"
      tools:
-       python: "3.9"
+       python: "3.11"
 
    # Build from the docs/ directory with Sphinx
    sphinx:
@@ -64,8 +64,8 @@ A configuration file with explicit dependencies looks like this:
    :caption: docs/requirements.txt
 
    # Defining the exact version will make sure things don't break
-   sphinx==4.2.0
-   sphinx_rtd_theme==1.0.0
+   sphinx==5.3.0
+   sphinx_rtd_theme==1.1.1
    readthedocs-sphinx-search==0.1.1
 
 Don't rely on implicit dependencies
@@ -88,9 +88,9 @@ for example:
       version: 2
 
       build:
-        os: "ubuntu-20.04"
+        os: "ubuntu-22.04"
         tools:
-          python: "3.9"
+          python: "3.11"
 
       sphinx:
         configuration: docs/conf.py
@@ -124,9 +124,9 @@ Some examples:
    .. code-block::
       :caption: docs/requirements.txt
 
-      sphinx==4.2.0
-      sphinx_rtd_theme==1.0.0
-      readthedocs-sphinx-search==0.1.1
+      sphinx==5.3.0
+      sphinx_rtd_theme==1.1.1
+      readthedocs-sphinx-search==0.1.2
 
    .. code-block:: yaml
       :caption: docs/environment.yaml
@@ -136,10 +136,10 @@ Some examples:
         - conda-forge
         - defaults
       dependencies:
-        - sphinx==4.2.0
-        - nbsphinx==0.8.1
+        - sphinx==5.3.0
+        - nbsphinx==0.8.10
         - pip:
-          - sphinx_rtd_theme==1.0.0
+          - sphinx_rtd_theme==1.1.1
 
 ❌ Bad:
    The latest or any other already installed version will be used,
@@ -197,49 +197,46 @@ and it generates a ``requirements.txt`` file with the full set of transitive dep
    .. code-block::
       :caption: docs/requirements.in
 
-      sphinx==4.2.0
+      sphinx==5.3.0
 
    .. code-block:: yaml
       :caption: docs/requirements.txt
 
-      # This file is autogenerated by pip-compile with python 3.7
-      # To update, run:
+      #
+      # This file is autogenerated by pip-compile with Python 3.10
+      # by the following command:
       #
       #    pip-compile docs.in
       #
       alabaster==0.7.12
           # via sphinx
-      babel==2.10.1
+      babel==2.11.0
           # via sphinx
-      certifi==2021.10.8
+      certifi==2022.12.7
           # via requests
-      charset-normalizer==2.0.12
+      charset-normalizer==2.1.1
           # via requests
-      docutils==0.17.1
+      docutils==0.19
           # via sphinx
-      idna==3.3
+      idna==3.4
           # via requests
-      imagesize==1.3.0
-          # via sphinx
-      importlib-metadata==4.11.3
+      imagesize==1.4.1
           # via sphinx
       jinja2==3.1.2
           # via sphinx
       markupsafe==2.1.1
           # via jinja2
-      packaging==21.3
+      packaging==22.0
           # via sphinx
-      pygments==2.11.2
+      pygments==2.13.0
           # via sphinx
-      pyparsing==3.0.8
-          # via packaging
-      pytz==2022.1
+      pytz==2022.7
           # via babel
-      requests==2.27.1
+      requests==2.28.1
           # via sphinx
       snowballstemmer==2.2.0
           # via sphinx
-      sphinx==4.4.0
+      sphinx==5.3.0
           # via -r docs.in
       sphinxcontrib-applehelp==1.0.2
           # via sphinx
@@ -253,9 +250,5 @@ and it generates a ``requirements.txt`` file with the full set of transitive dep
           # via sphinx
       sphinxcontrib-serializinghtml==1.1.5
           # via sphinx
-      typing-extensions==4.2.0
-          # via importlib-metadata
-      urllib3==1.26.9
+      urllib3==1.26.13
           # via requests
-      zipp==3.8.0
-          # via importlib-metadata