Merge branch 'master' of github.com:readthedocs/readthedocs.org into humitos/build-jobs-config

Author: humitos

.circleci/config.yml

@@ -1,5 +1,8 @@
 version: 2.1
 
+orbs:
+  codecov: codecov/[email protected]
+
 jobs:
   tests:
     docker:
@@ -16,7 +19,8 @@ jobs:
       - run: git submodule sync
       - run: git submodule update --init
       - run: pip install --user tox
-      - run: tox -e py38,codecov
+      - run: tox -e py38
+      - codecov/upload
 
   tests-embedapi:
     docker:

CHANGELOG.rst

@@ -1,3 +1,21 @@
+Version 7.4.2
+-------------
+
+:Date: March 14, 2022
+
+* `@stsewd <https://github.com/stsewd>`__: CI: fix codecov again (`#9007 <https://github.com/readthedocs/readthedocs.org/pull/9007>`__)
+* `@stsewd <https://github.com/stsewd>`__: CI: fix codecov (`#9006 <https://github.com/readthedocs/readthedocs.org/pull/9006>`__)
+* `@agjohnson <https://github.com/agjohnson>`__: Release 7.4.1 (`#9004 <https://github.com/readthedocs/readthedocs.org/pull/9004>`__)
+* `@pyup-bot <https://github.com/pyup-bot>`__: pyup:  Scheduled weekly dependency update for week 10 (`#9003 <https://github.com/readthedocs/readthedocs.org/pull/9003>`__)
+* `@humitos <https://github.com/humitos>`__: Upgrade common submodule (`#9001 <https://github.com/readthedocs/readthedocs.org/pull/9001>`__)
+* `@humitos <https://github.com/humitos>`__: Build: `RepositoryError` message (`#8999 <https://github.com/readthedocs/readthedocs.org/pull/8999>`__)
+* `@stsewd <https://github.com/stsewd>`__: Search: fix integration with latest sphinx (`#8994 <https://github.com/readthedocs/readthedocs.org/pull/8994>`__)
+* `@humitos <https://github.com/humitos>`__: API: validate `RemoteRepository` when creating a `Project` (`#8983 <https://github.com/readthedocs/readthedocs.org/pull/8983>`__)
+* `@stsewd <https://github.com/stsewd>`__: Tests: fix mock.patch order (`#8909 <https://github.com/readthedocs/readthedocs.org/pull/8909>`__)
+* `@humitos <https://github.com/humitos>`__: Celery: remove queue priority (`#8848 <https://github.com/readthedocs/readthedocs.org/pull/8848>`__)
+* `@dogukanteber <https://github.com/dogukanteber>`__: Use django-storages' manifest files class instead of the overriden class (`#8781 <https://github.com/readthedocs/readthedocs.org/pull/8781>`__)
+* `@abravalheri <https://github.com/abravalheri>`__: Improve displayed version name when building from PR (`#8237 <https://github.com/readthedocs/readthedocs.org/pull/8237>`__)
+
 Version 7.4.1
 -------------
 

docs/user/builds.rst

@@ -80,10 +80,17 @@ The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment va
    :widths: 15, 10, 30
 
    ``READTHEDOCS``, Whether the build is running inside RTD, ``True``
-   ``READTHEDOCS_VERSION``, The RTD name of the version which is being built, ``latest``
+   ``READTHEDOCS_VERSION``, The RTD slug of the version which is being built, ``latest``
+   ``READTHEDOCS_VERSION_NAME``, Corresponding version name as displayed in RTD's version switch menu, ``stable``
+   ``READTHEDOCS_VERSION_TYPE``, Type of the event triggering the build, ``branch`` | ``tag`` | ``external`` (for :doc:`pull request builds </pull-requests>`) | ``unknown``
    ``READTHEDOCS_PROJECT``, The RTD slug of the project which is being built, ``my-example-project``
    ``READTHEDOCS_LANGUAGE``, The RTD language slug of the project which is being built, ``en``
 
+.. note::
+
+   The term slug is used to refer to a unique string across projects/versions containing ASCII characters only.
+   This value is used in the URLs of your documentation.
+
 
 .. tip::
 

readthedocs/api/v2/templates/restapi/footer.html

@@ -6,7 +6,7 @@
   <div class="rst-versions rst-badge" data-toggle="rst-versions">
     <span class="rst-current-version" data-toggle="rst-current-version">
       <span class="fa fa-book">&nbsp;</span>
-      v: {{ current_version }}
+      v: {{ current_version.explicit_name }}
       <span class="fa fa-caret-down"></span>
     </span>
     <div class="rst-other-versions">
@@ -18,7 +18,7 @@
         <dt>{% trans "Languages" %}</dt>
 
         {# Output the main project language since it isn't included in translations list #}
-        
+
         <dd {% if main_project.language == current_language %} class="rtd-current-item" {% endif %}>
           <a href="{{ main_project.get_docs_url }}{{ path }}">{{ main_project.language }}</a>
         </dd>
@@ -41,8 +41,8 @@
       <dl>
         <dt>{% trans "Versions" %}</dt>
         {% for version in versions %}
-        <dd {% if version.verbose_name == current_version %} class="rtd-current-item" {% endif %}>
-          <a href="{{ version.get_subdomain_url }}{{ path|default_if_none:"" }}">{{ version.slug }}</a>
+        <dd {% if version == current_version %} class="rtd-current-item" {% endif %}>
+          <a href="{{ version.get_subdomain_url }}{{ path|default_if_none:"" }}">{{ version.verbose_name }}</a>
         </dd>
         {% endfor %}
       </dl>

readthedocs/api/v2/views/footer_views.py

@@ -1,9 +1,9 @@
 """Endpoint to generate footer HTML."""
 
-import structlog
 import re
 from functools import lru_cache
 
+import structlog
 from django.conf import settings
 from django.shortcuts import get_object_or_404
 from django.template import loader as template_loader
@@ -162,18 +162,18 @@ def _get_context(self):
                 path = page_slug + '.html'
 
         context = {
-            'project': project,
-            'version': version,
-            'path': path,
-            'downloads': version.get_downloads(pretty=True),
-            'current_version': version.verbose_name,
-            'versions': self._get_active_versions_sorted(),
-            'main_project': main_project,
-            'translations': main_project.translations.all(),
-            'current_language': project.language,
-            'new_theme': new_theme,
-            'settings': settings,
-            'github_edit_url': version.get_github_url(
+            "project": project,
+            "version": version,
+            "path": path,
+            "downloads": version.get_downloads(pretty=True),
+            "current_version": version,
+            "versions": self._get_active_versions_sorted(),
+            "main_project": main_project,
+            "translations": main_project.translations.all(),
+            "current_language": project.language,
+            "new_theme": new_theme,
+            "settings": settings,
+            "github_edit_url": version.get_github_url(
                 docroot,
                 page_slug,
                 source_suffix,

readthedocs/builds/models.py

@@ -14,10 +14,7 @@
 from django.utils import timezone
 from django.utils.translation import gettext
 from django.utils.translation import gettext_lazy as _
-from django_extensions.db.fields import (
-    CreationDateTimeField,
-    ModificationDateTimeField,
-)
+from django_extensions.db.fields import CreationDateTimeField, ModificationDateTimeField
 from django_extensions.db.models import TimeStampedModel
 from polymorphic.models import PolymorphicModel
 
@@ -30,9 +27,6 @@
     BUILD_STATUS_CHOICES,
     BUILD_TYPES,
     EXTERNAL,
-    GENERIC_EXTERNAL_VERSION_NAME,
-    GITHUB_EXTERNAL_VERSION_NAME,
-    GITLAB_EXTERNAL_VERSION_NAME,
     INTERNAL,
     LATEST,
     NON_REPOSITORY_VERSIONS,
@@ -57,6 +51,7 @@
     VersionQuerySet,
 )
 from readthedocs.builds.utils import (
+    external_version_name,
     get_bitbucket_username_repo,
     get_github_username_repo,
     get_gitlab_username_repo,
@@ -211,6 +206,27 @@ def is_private(self):
     def is_external(self):
         return self.type == EXTERNAL
 
+    @property
+    def explicit_name(self):
+        """
+        Version name that is explicit about external origins.
+
+        For example, if a version originates from GitHub pull request #4, then
+        ``version.explicit_name == "#4 (PR)"``.
+
+        On the other hand, Versions associated with regular RTD builds
+        (e.g. new tags or branches), simply return :obj:`~.verbose_name`.
+        This means that a regular git tag named **v4** will correspond to
+        ``version.explicit_name == "v4"``.
+        """
+        if not self.is_external:
+            return self.verbose_name
+
+        template = "#{name} ({abbrev})"
+        external_origin = external_version_name(self)
+        abbrev = "".join(word[0].upper() for word in external_origin.split())
+        return template.format(name=self.verbose_name, abbrev=abbrev)
+
     @property
     def ref(self):
         if self.slug == STABLE:
@@ -946,16 +962,7 @@ def can_rebuild(self):
 
     @property
     def external_version_name(self):
-        if self.is_external:
-            if self.project.git_provider_name == GITHUB_BRAND:
-                return GITHUB_EXTERNAL_VERSION_NAME
-
-            if self.project.git_provider_name == GITLAB_BRAND:
-                return GITLAB_EXTERNAL_VERSION_NAME
-
-            # TODO: Add External Version Name for BitBucket.
-            return GENERIC_EXTERNAL_VERSION_NAME
-        return None
+        return external_version_name(self)
 
     def using_latest_config(self):
         if self.config:
@@ -1324,7 +1331,7 @@ def match(self, version, match_arg):
                 pattern=match_arg,
                 version_slug=version.slug,
             )
-        except Exception as e:
+        except Exception:
             log.exception('Error parsing regex.', exc_info=True)
         return False, None
 

readthedocs/builds/utils.py

@@ -1,15 +1,21 @@
 """Utilities for the builds app."""
-from time import monotonic
-
 from contextlib import contextmanager
+from time import monotonic
 
 from django.core.cache import cache
 
-from readthedocs.builds.constants import EXTERNAL
+from readthedocs.builds.constants import (
+    EXTERNAL,
+    GENERIC_EXTERNAL_VERSION_NAME,
+    GITHUB_EXTERNAL_VERSION_NAME,
+    GITLAB_EXTERNAL_VERSION_NAME,
+)
 from readthedocs.projects.constants import (
     BITBUCKET_REGEXS,
+    GITHUB_BRAND,
     GITHUB_PULL_REQUEST_URL,
     GITHUB_REGEXS,
+    GITLAB_BRAND,
     GITLAB_MERGE_REQUEST_URL,
     GITLAB_REGEXS,
 )
@@ -79,6 +85,23 @@ def get_vcs_url(*, project, version_type, version_name):
     return project.repo.replace('git://', 'https://').replace('.git', '') + url
 
 
+def external_version_name(build_or_version):
+    """Returns a string identifying the external build/version's nature."""
+    if not build_or_version.is_external:
+        return None
+
+    project = build_or_version.project
+
+    if project.git_provider_name == GITHUB_BRAND:
+        return GITHUB_EXTERNAL_VERSION_NAME
+
+    if project.git_provider_name == GITLAB_BRAND:
+        return GITLAB_EXTERNAL_VERSION_NAME
+
+    # TODO: Add External Version Name for BitBucket.
+    return GENERIC_EXTERNAL_VERSION_NAME
+
+
 @contextmanager
 def memcache_lock(lock_id, oid):
     """

readthedocs/core/static-src/core/js/doc-embed/search.js

@@ -53,6 +53,17 @@ function attach_elastic_search_query_sphinx(data) {
         search_url.search = '?q=' + $.urlencode(query) + '&project=' + project +
                             '&version=' + version + '&language=' + language;
 
+        /*
+         * Compatibility function to set a text to a Node or JQuery object.
+         */
+        var setText = function (node, text) {
+          if (node.jquery) {
+            node.text(text);
+          } else {
+            node.innerText = text;
+          }
+        };
+
         search_def
             .then(function (data) {
                 var results = data.results || [];
@@ -61,7 +72,7 @@ function attach_elastic_search_query_sphinx(data) {
                     for (var i = 0; i < results.length; i += 1) {
                         var result = results[i];
                         var blocks = result.blocks;
-                        var list_item = $('<li style="display: none;"></li>');
+                        var list_item = $('<li>');
 
                         var title = result.title;
                         // if highlighted title is present, use that.
@@ -188,10 +199,14 @@ function attach_elastic_search_query_sphinx(data) {
                             }
                         }
 
-                        Search.output.append(list_item);
-                        list_item.slideDown(5);
+                        if (Search.output.jquery) {
+                          Search.output.append(list_item);
+                        } else {
+                          Search.output.appendChild(list_item.get(0));
+                        }
                     }
-                    Search.status.text(
+                    setText(
+                        Search.status,
                         _('Search finished, found %s page(s) matching the search query.').replace('%s', results.length)
                     );
                 } else {
@@ -206,8 +221,7 @@ function attach_elastic_search_query_sphinx(data) {
             .always(function () {
                 $('#search-progress').empty();
                 Search.stopPulse();
-                Search.title.text(_('Search Results'));
-                Search.status.fadeIn(500);
+                setText(Search.title, _('Search Results'));
             });
 
         $.ajax({

readthedocs/core/static/core/js/readthedocs-doc-embed.js

@@ -204,6 +204,8 @@ def test_get_env_vars_default(self, load_yaml_config):
             "NO_COLOR": "1",
             "READTHEDOCS": "True",
             "READTHEDOCS_VERSION": self.version.slug,
+            "READTHEDOCS_VERSION_TYPE": self.version.type,
+            "READTHEDOCS_VERSION_NAME": self.version.verbose_name,
             "READTHEDOCS_PROJECT": self.project.slug,
             "READTHEDOCS_LANGUAGE": self.project.language,
             "BIN_PATH": os.path.join(

readthedocs/projects/tests/test_build_tasks.py

@@ -491,7 +491,8 @@ def setUp(self):
         self.project = get(Project)
         self.version = get(
             Version,
-            project=self.project
+            project=self.project,
+            type=BRANCH,
         )
 
         get(

readthedocs/rtd_tests/tests/test_builds.py

@@ -11,7 +11,7 @@
 from readthedocs.builds.constants import BRANCH, EXTERNAL, LATEST, TAG
 from readthedocs.builds.models import Version
 from readthedocs.core.middleware import ReadTheDocsSessionMiddleware
-from readthedocs.projects.constants import PUBLIC
+from readthedocs.projects.constants import GITHUB_BRAND, GITLAB_BRAND, PUBLIC
 from readthedocs.projects.models import Project
 
 
@@ -72,6 +72,29 @@ def test_footer_dont_show_version_warning(self):
         self.assertFalse(r.data['show_version_warning'])
         self.assertEqual(r.context['main_project'], self.pip)
 
+    def test_footer_show_explicit_name_for_external_version(self):
+        project = Project.objects.get(slug="pip")
+        version = project.versions.get(slug=LATEST)
+        version.type = EXTERNAL
+        version.verbose_name = "4"
+        version.save()
+        self.url = (
+            reverse("footer_html")
+            + f"?project={project.slug}&version={version.slug}&page=index&docroot=/"
+        )
+
+        git_provider_name = "readthedocs.projects.models.Project.git_provider_name"
+        with mock.patch(git_provider_name, GITHUB_BRAND):
+            r = self.render()
+            self.assertIn("#4 (PR)", r.data["html"])
+            self.assertNotIn("#4 (MR)", r.data["html"])
+            self.assertNotIn("#4 (EV)", r.data["html"])
+        with mock.patch(git_provider_name, GITLAB_BRAND):
+            r = self.render()
+            self.assertIn("#4 (MR)", r.data["html"])
+            self.assertNotIn("#4 (PR)", r.data["html"])
+            self.assertNotIn("#4 (EV)", r.data["html"])
+
     def test_footer_dont_show_version_warning_for_external_versions(self):
         self.latest.type = EXTERNAL
         self.latest.save()

readthedocs/rtd_tests/tests/test_footer.py

@@ -4,7 +4,7 @@
 
 psycopg2==2.9.3
 gunicorn==20.1.0
-django-redis-cache==3.0.0
+django-redis-cache==3.0.1
 
 #For resizing images
 pillow==9.0.1