Implement hidden state for versions

docs/api/v3.rst

@@ -394,6 +394,7 @@ Version detail
             "ref": "19.0.2",
             "built": true,
             "active": true,
+            "hidden": false,
             "type": "tag",
             "last_build": "{BUILD}",
             "downloads": {
@@ -460,7 +461,8 @@ Version update
     .. sourcecode:: json
 
         {
-            "active": true
+            "active": true,
+            "hidden": false
         }
 
     :statuscode 204: Updated successfully

docs/guides/hiding-a-version.rst

@@ -0,0 +1,20 @@
+Hide a Version and Keep its Docs Online
+=======================================
+
+If you manage a project with a lot of versions,
+the version (flyout) menu of your docs can be easily overwhelmed and hard to navigate.
+
+.. figure::  /_static/images/guides/flyout-overwhelmed.png
+   :align: center
+
+   Overwhelmed flyout menu
+
+You can deactivate the version to remove its docs,
+but removing its docs isn't always an option.
+To don't list a version in the flyout menu while keeping its docs online, you can mark it as hidden.
+Go to the :guilabel:`Versions` tab of your project, click on :guilabel:`Edit` and mark the ``Hidden`` option.
+
+Users that have a link to your old version will still be able to see your docs.
+And new users can see all your versions (including hidden versions) in the versions tab of your project at ``https://readthedocs.org/projects/<your-project>/versions/``
+
+Check the docs about :ref:`versions' states <versions:States>` for more information.

docs/guides/index.rst

@@ -36,15 +36,16 @@ These guides will help you customize or tune aspects of Read the Docs.
     autobuild-docs-for-pull-requests
     build-notifications
     build-using-too-many-resources
-    technical-docs-seo-guide
     canonical
     conda
     environment-variables
     feature-flags
     google-analytics
+    hiding-a-version
     searching-with-readthedocs
     sitemaps
     specifying-dependencies
+    technical-docs-seo-guide
     wipe-environment
 
 

docs/versions.rst

@@ -58,6 +58,48 @@ they will be redirected to the **Default version**.
 This defaults to **latest**,
 but could also point to your latest released version.
 
+States
+------
+
+States define the visibility of a version across the site.
+You can change the states of a version from the :guilabel:`Versions` tab of your project.
+
+Active
+~~~~~~
+
+- **Active**
+
+  - Docs for this version are visible
+  - Builds can be triggered for this version
+
+- **Inactive**
+
+  - Docs for this version aren't visible
+  - Builds can't be triggered for this version
+
+When you deactivate a version, its docs are removed.
+
+Hidden
+~~~~~~
+
+- **Not hidden and Active**
+
+  - This version is listed on the version (flyout) menu on the docs site
+  - This version is shown in search results on the docs site
+
+- **Hidden and Active**
+
+  - This version isn't listed on the version (flyout) menu on the docs site
+  - This version isn't show in search results from another version on the docs site
+    (like on search results from a superproject)
+
+Hiding a version doesn't make it private,
+any user with a link to its docs would be able to see it.
+This is useful when:
+
+- You no longer support a version, but you don't want to remove its docs.
+- You have a work in progress version and don't want to publish its docs just yet. 
+
 Version warning
 ---------------
 

readthedocs/api/v2/views/footer_views.py

@@ -127,6 +127,7 @@ def _get_active_versions_sorted(self):
         project = self._get_project()
         versions = project.ordered_active_versions(
             user=self.request.user,
+            include_hidden=False,
         )
         return versions
 

readthedocs/api/v3/serializers.py

@@ -219,6 +219,7 @@ class Meta:
             'ref',
             'built',
             'active',
+            'hidden',
             'type',
             'downloads',
             'urls',

readthedocs/api/v3/tests/responses/projects-detail.json

@@ -2,6 +2,7 @@
     "active_versions": [
         {
             "active": true,
+            "hidden": false,
             "built": true,
             "downloads": {
                 "epub": "https://project.readthedocs.io/_/downloads/en/v1.0/epub/",

readthedocs/api/v3/tests/responses/projects-versions-builds-list_POST.json

@@ -72,6 +72,7 @@
     "triggered": true,
     "version": {
         "active": true,
+        "hidden": false,
         "built": true,
         "downloads": {
             "epub": "https://project.readthedocs.io/_/downloads/en/v1.0/epub/",

readthedocs/api/v3/tests/responses/projects-versions-detail.json

@@ -1,5 +1,6 @@
 {
     "active": true,
+    "hidden": false,
     "built": true,
     "downloads": {
         "epub": "https://project.readthedocs.io/_/downloads/en/v1.0/epub/",

readthedocs/builds/forms.py

@@ -3,7 +3,10 @@
 import re
 import textwrap
 
+from crispy_forms.helper import FormHelper
+from crispy_forms.layout import HTML, Fieldset, Layout
 from django import forms
+from django.template.loader import render_to_string
 from django.utils.translation import ugettext_lazy as _
 
 from readthedocs.builds.constants import (
@@ -22,7 +25,32 @@ class VersionForm(HideProtectedLevelMixin, forms.ModelForm):
 
     class Meta:
         model = Version
-        fields = ['active', 'privacy_level']
+        states_fields = ['active', 'hidden']
+        privacy_fields = ['privacy_level']
+        fields = (
+            *states_fields,
+            *privacy_fields,
+        )
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        self.helper = FormHelper()
+        self.helper.layout = Layout(
+            Fieldset(
+                _('States'),
+                HTML(render_to_string('projects/project_version_states_help_text.html')),
+                *self.Meta.states_fields,
+            ),
+            Fieldset(
+                _('Privacy'),
+                *self.Meta.privacy_fields,
+            ),
+            HTML(render_to_string(
+                'projects/project_version_submit.html',
+                context={'version': self.instance},
+            )),
+        )
 
     def clean_active(self):
         active = self.cleaned_data['active']

readthedocs/builds/migrations/0016_add_hidden_field_to_version.py

@@ -0,0 +1,18 @@
+# Generated by Django 2.2.11 on 2020-03-18 01:47
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('builds', '0015_uploading_build_state'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='version',
+            name='hidden',
+            field=models.BooleanField(default=False, help_text='Hide this version from the version (flyout) menu and search results?', verbose_name='Hidden'),
+        ),
+    ]

readthedocs/builds/migrations/0017_migrate_protected_versions_to_hidden

@@ -0,0 +1,20 @@
+# Generated by Django 2.2.11 on 2020-03-18 18:27
+
+from django.db import migrations
+
+
+def forwards_func(apps, schema_editor):
+    """Migrate all protected versions to be hidden."""
+    Version = apps.get_model('builds', 'Version')
+    Version.objects.filter(privacy_level='protected').update(hidden=True)
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('builds', '0016_add_hidden_field_to_version'),
+    ]
+
+    operations = [
+        migrations.RunPython(forwards_func),
+    ]

readthedocs/builds/models.py

@@ -136,6 +136,11 @@ class Version(models.Model):
         default=settings.DEFAULT_VERSION_PRIVACY_LEVEL,
         help_text=_('Level of privacy for this Version.'),
     )
+    hidden = models.BooleanField(
+        _('Hidden'),
+        default=False,
+        help_text=_('Hide this version from the version (flyout) menu and search results?')
+    )
     machine = models.BooleanField(_('Machine Created'), default=False)
 
     # Whether the latest successful build for this version contains certain media types

readthedocs/builds/querysets.py

@@ -24,14 +24,16 @@ def _add_user_repos(self, queryset, user):
             queryset = user_queryset | queryset
         return queryset
 
-    def public(self, user=None, project=None, only_active=True):
+    def public(self, user=None, project=None, only_active=True, include_hidden=True):
         queryset = self.filter(privacy_level=constants.PUBLIC)
         if user:
             queryset = self._add_user_repos(queryset, user)
         if project:
             queryset = queryset.filter(project=project)
         if only_active:
             queryset = queryset.filter(active=True)
+        if not include_hidden:
+            queryset = queryset.filter(hidden=False)
         return queryset.distinct()
 
     def protected(self, user=None, project=None, only_active=True):

readthedocs/rtd_tests/tests/test_footer.py

@@ -197,6 +197,33 @@ def test_index_pages_sphinx_htmldir(self):
         self.assertNotIn('/en/latest/foo/index/bar.html', response.data['html'])
         self.assertNotIn('/en/latest/foo/index/bar/index.html', response.data['html'])
 
+    def test_hidden_versions(self):
+        hidden_version = get(
+            Version,
+            slug='2.0',
+            hidden=True,
+            privacy_level=PUBLIC,
+            project=self.pip,
+        )
+
+        # The hidden version doesn't appear on the footer
+        self.url = (
+            reverse('footer_html') +
+            f'?project={self.pip.slug}&version={self.latest.slug}&page=index&docroot=/'
+        )
+        response = self.render()
+        self.assertIn('/en/latest/', response.data['html'])
+        self.assertNotIn('/en/2.0/', response.data['html'])
+
+        # We can access the hidden version, but it doesn't appear on the footer
+        self.url = (
+            reverse('footer_html') +
+            f'?project={self.pip.slug}&version={hidden_version.slug}&page=index&docroot=/'
+        )
+        response = self.render()
+        self.assertIn('/en/latest/', response.data['html'])
+        self.assertNotIn('/en/2.0/', response.data['html'])
+
 
 class TestFooterHTML(BaseTestFooterHTML, TestCase):
 

readthedocs/search/api.py

@@ -167,14 +167,15 @@ def get_all_projects(self):
         main_version = self._get_version()
         main_project = self._get_project()
 
+        all_projects = [main_project]
+
         subprojects = Project.objects.filter(
             superprojects__parent_id=main_project.id,
         )
-        all_projects = []
-        for project in list(subprojects) + [main_project]:
+        for project in subprojects:
             version = (
                 Version.internal
-                .public(user=self.request.user, project=project)
+                .public(user=self.request.user, project=project, include_hidden=False)
                 .filter(slug=main_version.slug)
                 .first()
             )

readthedocs/search/tests/test_api.py

@@ -282,6 +282,47 @@ def test_get_all_projects_returns_empty_results(self, api_client, project):
         data = resp.data['results']
         assert len(data) == 0
 
+    def test_doc_search_hidden_versions(self, api_client, all_projects):
+        """Test Document search return results from subprojects also"""
+        project = all_projects[0]
+        subproject = all_projects[1]
+        version = project.versions.all()[0]
+        # Add another project as subproject of the project
+        project.add_subproject(subproject)
+
+        version_subproject = subproject.versions.first()
+        version_subproject.hidden = True
+        version_subproject.save()
+
+        # Now search with subproject content but explicitly filter by the parent project
+        query = get_search_query_from_project_file(project_slug=subproject.slug)
+        search_params = {
+            'q': query,
+            'project': project.slug,
+            'version': version.slug
+        }
+        resp = self.get_search(api_client, search_params)
+        assert resp.status_code == 200
+
+        # The version from the subproject is hidden, so isn't show on the results.
+        data = resp.data['results']
+        assert len(data) == 0
+
+        # Now search on the subproject with hidden version
+        query = get_search_query_from_project_file(project_slug=subproject.slug)
+        search_params = {
+            'q': query,
+            'project': subproject.slug,
+            'version': version_subproject.slug
+        }
+        resp = self.get_search(api_client, search_params)
+        assert resp.status_code == 200
+        # We can still search inside the hidden version
+        data = resp.data['results']
+        assert len(data) == 1
+        first_result = data[0]
+        assert first_result['project'] == subproject.slug
+
 
 class TestDocumentSearch(BaseTestDocumentSearch):
 

readthedocs/templates/projects/project_version_detail.html

@@ -1,5 +1,6 @@
 {% extends "projects/base_project.html" %}
 
+{% load crispy_forms_tags %}
 {% load i18n %}
 {% load privacy_tags %}
 
@@ -32,14 +33,6 @@ <h2> Editing {{ version.slug }} </h2>
       {% endif %}
     {% endif %}
 
+    {% crispy form %}
 
-    <form method="post" action=".">
-      {% csrf_token %}
-      {{ form.as_p }}
-      <p>
-        <input style="display: inline;" type="submit" value="{% trans "Save" %}">
-        {% trans "or" %}
-        <a href="{% url "wipe_version" version.project.slug version.slug %}">{% trans "wipe "%}</a>
-      </p>
-    </form>
 {% endblock %}

readthedocs/templates/projects/project_version_states_help_text.html

@@ -0,0 +1,7 @@
+{% load i18n %}
+
+<p>
+  {% blocktrans trimmed with docs_link="https://docs.readthedocs.io/page/versions.html#states" %}
+    Learn more about states <a href="{{ docs_link }}">here</a>.
+  {% endblocktrans %}
+</p>

readthedocs/templates/projects/project_version_submit.html

@@ -0,0 +1,7 @@
+{% load i18n %}
+
+<p>
+  <input style="display: inline;" type="submit" value="{% trans "Save" %}">
+  {% trans "or" %}
+  <a href="{% url "wipe_version" version.project.slug version.slug %}">{% trans "wipe "%}</a>
+</p>