Addopt review suggestions from readthedocs#8237

docs/builds.rst

@@ -89,12 +89,11 @@ The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment va
 
 .. note::
 
-   - The term "slug" is used here to indicate a string without some types characters
-     considered special in certain circunstances. The version slug can contain some
-     characters not usually present in other slugs.
+   - 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.
 
-   - The ``external`` value for ``READTHEDOCS_VERSION_TYPE`` will usually be
-     associated with builds triggered by pull requests. See :doc:`/pull-requests`.
+   - If ``READTHEDOCS_VERSION_TYPE`` is ``external``,
+     it means that the version was built from pull request. See :doc:`/pull-requests`.
 
 
 .. 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: {{ version.explicit_name }}
+      v: {{ current_version.explicit_name }}
       <span class="fa fa-caret-down"></span>
     </span>
     <div class="rst-other-versions">
@@ -41,7 +41,7 @@
       <dl>
         <dt>{% trans "Versions" %}</dt>
         {% for version in versions %}
-        <dd {% if version.verbose_name == current_version %} class="rtd-current-item" {% endif %}>
+        <dd {% if version == current_version %} class="rtd-current-item" {% endif %}>
           <a href="{{ version.get_subdomain_url }}{{ path|default_if_none:"" }}">{{ version.explicit_name }}</a>
         </dd>
         {% endfor %}

readthedocs/api/v2/views/footer_views.py

@@ -166,7 +166,7 @@ def _get_context(self):
             'version': version,
             'path': path,
             'downloads': version.get_downloads(pretty=True),
-            'current_version': version.verbose_name,
+            'current_version': version,
             'versions': self._get_active_versions_sorted(),
             'main_project': main_project,
             'translations': main_project.translations.all(),

readthedocs/builds/models.py

@@ -56,7 +56,6 @@
     VersionQuerySet,
 )
 from readthedocs.builds.utils import (
-    abbrev,
     external_version_name,
     get_bitbucket_username_repo,
     get_github_username_repo,
@@ -200,41 +199,26 @@ def is_external(self):
         return self.type == EXTERNAL
 
     @property
-    def explicit_external_name(self):
+    def explicit_name(self):
         """
-        If the version is external, returns a name that is explicit about it.
+        Version name that is explicit about external origins.
 
         For example, if a version originates from GitHub pull request #4, then
-        ``version.explicit_external_name == "#4 (PR)"``.
+        ``version.explicit_name == "#4 (PR)"``.
 
-        On the other hand, if the version is associated with a git tag **v4**
-        and was created by a regular ReadTheDocs build, then
-        ``version.explicit_external_name == None``.
+        On the other hand, Versions associated with regular ReadTheDocs 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"``.
         """
         external_origin = external_version_name(self)
 
         if not external_origin:
-            return None
+            return self.verbose_name
 
-        origin_abbrev = abbrev(external_origin)
         template = '#{name} ({abbrev})'
-        return template.format(name=self.verbose_name, abbrev=origin_abbrev)
-
-    @property
-    def explicit_name(self):
-        """
-        Version name that is explicit about external origins.
-
-        This property is similar to :obj:`~.explicit_external_name` but instead
-        of returning ``None`` for versions associated with regular ReadTheDocs
-        builds (not external), simply return :obj:`~.verbose_name`.
-
-        For example, ``version.explicit_name == "#3 (MR)"`` when version
-        originates from GitLab merge request #3;
-        or ``version.explicit_name == "v3"``
-        when version originates from a regular git tag named **v3**.
-        """
-        return self.explicit_external_name or self.verbose_name
+        abbrev = ''.join(word[0].upper() for word in external_origin.split())
+        return template.format(name=self.verbose_name, abbrev=abbrev)
 
     @property
     def ref(self):

readthedocs/builds/utils.py

@@ -103,16 +103,6 @@ def external_version_name(build_or_version):
     return GENERIC_EXTERNAL_VERSION_NAME
 
 
-def abbrev(string):
-    """
-    Returns an abbreviation for the given string.
-
-    The abbreviation is formed for the first letter in each word in the string,
-    capitalized.
-    """
-    return ''.join(word[0].upper() for word in string.split())
-
-
 @contextmanager
 def memcache_lock(lock_id, oid):
     """

readthedocs/projects/tasks.py

@@ -318,7 +318,7 @@ def get_rtd_env_vars(self):
             'READTHEDOCS': 'True',
             'READTHEDOCS_VERSION': self.version.slug,
             'READTHEDOCS_VERSION_TYPE': self.version.type,
-            'READTHEDOCS_VERSION_NAME': self.version.explicit_name,
+            'READTHEDOCS_VERSION_NAME': self.version.verbose_name,
             'READTHEDOCS_PROJECT': self.project.slug,
             'READTHEDOCS_LANGUAGE': self.project.language,
         }