Merge branch 'master' into humitos/document-share-sphinx-doctree-flag

Author: humitos

docs/_static/images/guides/flyout-overwhelmed.png

@@ -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/api/v3.rst

@@ -4,10 +4,10 @@ Feature Flags
 Read the Docs offers some additional flag settings which can be only be configured by the site admin.
 These are optional settings and you might not need it for every project.
 By default, these flags are disabled for every project.
-A separate request can be made by opening an issue on our `github`_ to enable
+A separate request can be made by `contacting us via email`_ to enable
 or disable one or more of these featured flags for a particular project.
 
-.. _github: https://github.com/readthedocs/readthedocs.org
+.. _contacting us via email: mailto:support@readthedocs.org
 
 Available Flags
 ---------------

docs/guides/feature-flags.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 not 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/hiding-a-version.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/guides/index.rst

@@ -58,6 +58,53 @@ 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. 
+
+.. note::
+
+   Active versions that are hidden will be listed as ``Disallow: /path/to/version/``
+   in the default `robots.txt file <https://www.robotstxt.org/>`__ created by Read the Docs.
+
 Version warning
 ---------------
 

docs/versions.rst

@@ -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/v2/views/footer_views.py

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

readthedocs/api/v3/serializers.py

@@ -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-detail.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-builds-list_POST.json

@@ -1,5 +1,6 @@
 {
     "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

@@ -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,36 @@ 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)
+
+        # TODO: remove when this field is no-nullable
+        self.fields['hidden'].widget = forms.CheckboxInput()
+        self.fields['hidden'].empty_value = False
+
+        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/forms.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', '0017_builds_deterministic_order_index'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='version',
+            name='hidden',
+            field=models.BooleanField(null=True, default=False, help_text='Hide this version from the version (flyout) menu and search results?', verbose_name='Hidden'),
+        ),
+    ]

readthedocs/builds/migrations/0018_add_hidden_field_to_version.py

@@ -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', '0018_add_hidden_field_to_version'),
+    ]
+
+    operations = [
+        migrations.RunPython(forwards_func),
+    ]

readthedocs/builds/migrations/0019_migrate_protected_versions_to_hidden.py

@@ -78,6 +78,8 @@
     MEDIA_TYPES,
     PRIVACY_CHOICES,
     SPHINX,
+    SPHINX_HTMLDIR,
+    SPHINX_SINGLEHTML,
 )
 from readthedocs.projects.models import APIProject, Project
 from readthedocs.projects.version_handling import determine_stable_version
@@ -136,6 +138,13 @@ class Version(models.Model):
         default=settings.DEFAULT_VERSION_PRIVACY_LEVEL,
         help_text=_('Level of privacy for this Version.'),
     )
+    hidden = models.BooleanField(
+        _('Hidden'),
+        # To avoid downtime during deploy, remove later.
+        null=True,
+        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
@@ -361,6 +370,10 @@ def supports_wipe(self):
         """Return True if version is not external."""
         return not self.type == EXTERNAL
 
+    @property
+    def is_sphinx_type(self):
+        return self.documentation_type in {SPHINX, SPHINX_HTMLDIR, SPHINX_SINGLEHTML}
+
     def get_subdomain_url(self):
         external = self.type == EXTERNAL
         return self.project.get_docs_url(

readthedocs/builds/models.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/builds/querysets.py

@@ -11,10 +11,10 @@
 import yaml
 from django.conf import settings
 from django.template import loader as template_loader
-from readthedocs.projects.constants import MKDOCS_HTML, MKDOCS
 
 from readthedocs.doc_builder.base import BaseBuilder
 from readthedocs.doc_builder.exceptions import MkDocsYAMLParseError
+from readthedocs.projects.constants import MKDOCS, MKDOCS_HTML
 from readthedocs.projects.models import Feature
 
 
@@ -314,17 +314,12 @@ def get_theme_name(self, mkdocs_config):
 
 
 class MkdocsHTML(BaseMkdocs):
+
     type = 'mkdocs'
     builder = 'build'
     build_dir = '_build/html'
 
 
-class MkdocsJSON(BaseMkdocs):
-    type = 'mkdocs_json'
-    builder = 'json'
-    build_dir = '_build/json'
-
-
 class SafeLoaderIgnoreUnknown(yaml.SafeLoader):  # pylint: disable=too-many-ancestors
 
     """

readthedocs/doc_builder/backends/mkdocs.py

@@ -50,6 +50,12 @@
         'memory': '7g',
         'time': 1800,
     })
+elif total_memory > 7000:
+    # This is to catch AWS instances that actually only have 7.5G memory
+    DOCKER_LIMITS.update({
+        'memory': '6g',
+        'time': 1800,
+    })
 elif total_memory > 4000:
     DOCKER_LIMITS.update({
         'memory': '3g',

readthedocs/doc_builder/constants.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 """Lookup tables for builders and backends."""
 from importlib import import_module
 
@@ -21,7 +19,6 @@
     'sphinx_singlehtmllocalmedia': sphinx.LocalMediaBuilder,
     # Other markup
     'mkdocs': mkdocs.MkdocsHTML,
-    'mkdocs_json': mkdocs.MkdocsJSON,
 }