Merge branch 'main' of github.com:readthedocs/readthedocs.org into diataxis/main

Author: benjaoming

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/
@@ -803,7 +804,9 @@ Schema
 
 You can see the complete schema
 `here <https://github.com/readthedocs/readthedocs.org/blob/main/readthedocs/rtd_tests/fixtures/spec/v2/schema.json>`_.
+This schema is available at `Schema Store`_, use it with your favorite editor for validation and autocompletion.
 
+.. _Schema Store: https://www.schemastore.org/
 
 Legacy ``build`` specification
 ------------------------------

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

readthedocs/api/v2/serializers.py

@@ -1,6 +1,9 @@
 """Defines serializers for each of our models."""
 
+import re
+
 from allauth.socialaccount.models import SocialAccount
+from django.conf import settings
 from rest_framework import serializers
 
 from readthedocs.builds.models import Build, BuildCommandResult, Version
@@ -133,11 +136,63 @@ class Meta:
         exclude = []
 
 
+class BuildCommandReadOnlySerializer(BuildCommandSerializer):
+
+    """
+    Serializer used on GETs to trim the commands' path.
+
+    Remove unreadable paths from the command outputs when returning it from the API.
+    We could make this change at build level, but we want to avoid undoable issues from now
+    and hack a small solution to fix the immediate problem.
+
+    This converts:
+        $ /usr/src/app/checkouts/readthedocs.org/user_builds/
+            <container_hash>/<project_slug>/envs/<version_slug>/bin/python
+        $ /home/docs/checkouts/readthedocs.org/user_builds/
+            <project_slug>/envs/<version_slug>/bin/python
+    into
+        $ python
+    """
+
+    command = serializers.SerializerMethodField()
+
+    def get_command(self, obj):
+        project_slug = obj.build.version.project.slug
+        version_slug = obj.build.version.slug
+        docroot = settings.DOCROOT.rstrip("/")  # remove trailing '/'
+
+        # Remove Docker hash from DOCROOT when running it locally
+        # DOCROOT contains the Docker container hash (e.g. b7703d1b5854).
+        # We have to remove it from the DOCROOT it self since it changes each time
+        # we spin up a new Docker instance locally.
+        container_hash = "/"
+        if settings.RTD_DOCKER_COMPOSE:
+            docroot = re.sub("/[0-9a-z]+/?$", "", settings.DOCROOT, count=1)
+            container_hash = "/([0-9a-z]+/)?"
+
+        regex = f"{docroot}{container_hash}{project_slug}/envs/{version_slug}(/bin/)?"
+        command = re.sub(regex, "", obj.command, count=1)
+        return command
+
+
 class BuildSerializer(serializers.ModelSerializer):
 
-    """Build serializer for user display, doesn't display internal fields."""
+    """
+    Build serializer for user display.
 
-    commands = BuildCommandSerializer(many=True, read_only=True)
+    This is the default serializer for Build objects over read-only operations from regular users.
+    Take into account that:
+
+    - It doesn't display internal fields (builder, _config)
+    - It's read-only for multiple fields (commands, project_slug, etc)
+
+    Staff users should use either:
+
+    - BuildAdminSerializer for write operations (e.g. builders hitting the API),
+    - BuildAdminReadOnlySerializer for read-only actions (e.g. dashboard retrieving build details)
+    """
+
+    commands = BuildCommandReadOnlySerializer(many=True, read_only=True)
     project_slug = serializers.ReadOnlyField(source='project.slug')
     version_slug = serializers.ReadOnlyField(source='get_version_slug')
     docs_url = serializers.SerializerMethodField()
@@ -160,13 +215,32 @@ def get_docs_url(self, obj):
 
 class BuildAdminSerializer(BuildSerializer):
 
-    """Build serializer for display to admin users and build instances."""
+    """
+    Build serializer to update Build objects from build instances.
+
+    It allows write operations on `commands` and display fields (e.g. builder)
+    that are allowed for admin purposes only.
+    """
+
+    commands = BuildCommandSerializer(many=True, read_only=True)
 
     class Meta(BuildSerializer.Meta):
         # `_config` should be excluded to avoid conflicts with `config`
         exclude = ('_config',)
 
 
+class BuildAdminReadOnlySerializer(BuildAdminSerializer):
+
+    """
+    Build serializer to retrieve Build objects from the dashboard.
+
+    It uses `BuildCommandReadOnlySerializer` to automatically parse the command
+    and trim the useless path.
+    """
+
+    commands = BuildCommandReadOnlySerializer(many=True, read_only=True)
+
+
 class SearchIndexSerializer(serializers.Serializer):
     q = serializers.CharField(max_length=500)
     project = serializers.CharField(max_length=500, required=False)