Docs: remove outdated and complex code and dependencies (#9981)

* Docs: remove outdated and complex code

This commit reduces the complexity of the documentation environment by removing
the requirement of having Django installed and loaded to build the docs.

* Remove the `djangodocs` and `doc_extensions`: they load the whole Django
application unnecesarily. We need to have a bunch of requirements installed just
because of this.

* Remove defaults from "Interesting settings" because all the default were
wrong. The Django extension was loading an invalid set of settings. This page
could be completely removed as well probably.

* Remove `featureflag` role because of the same reason (loads a whole Django
project). We were using it only to show a small description of the feature
flags. I wrote that text directly in the page. Feature flags are deprecated and
this page will probably deleted soon as well.

* Remove `buildpyversions` role also. Same reason. Manually wrote the versions
supported on each Docker image. This is used for the legacy images, tho. They
won't change since we don't maintain them anymore.

* Docs: reduce requirements drastically

Since we don't depend on Django anymore we can remove the `-r pip.txt`
dependency from the documentation.

This makes the documentation just to rely on Sphinx and some other extensions
only simplifying the environment a lot and running fast.

* Docs: don't install `pip.txt`

* Docs: remove missing `djangosetting` role

Author: humitos

.readthedocs.yml

@@ -8,7 +8,6 @@ sphinx:
 
 python:
   install:
-    - requirements: requirements/pip.txt
     - requirements: requirements/docs.txt
 
 build:

docs/conf.py

@@ -16,16 +16,6 @@
 
 from multiproject.utils import get_project
 
-sys.path.insert(0, os.path.abspath(".."))
-sys.path.append(os.path.dirname(__file__))
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "readthedocs.settings.docker_compose")
-
-# Load Django after sys.path and configuration setup
-# isort: split
-import django
-
-django.setup()
-
 sys.path.append(os.path.abspath("_ext"))
 extensions = [
     "multiproject",
@@ -34,8 +24,6 @@
     "sphinx.ext.intersphinx",
     "sphinxcontrib.httpdomain",
     "sphinxcontrib.video",
-    "djangodocs",
-    "doc_extensions",
     "sphinx_tabs.tabs",
     "sphinx-prompt",
     "notfound.extension",

docs/dev/settings.rst

@@ -4,8 +4,6 @@ Interesting Settings
 DOCKER_LIMITS
 -------------
 
-Default: :djangosetting:`DOCKER_LIMITS`
-
 A dictionary of limits to virtual machines. These limits include:
 
 time
@@ -27,8 +25,6 @@ SLUMBER_USERNAME
 .. Don't set this automatically, lest we leak something. We are using the dev
    settings in the conf.py, but it's probably a good idea to be safe.
 
-Default: ``test``
-
 The username to use when connecting to the Read the Docs API. Used for hitting the API while building the docs.
 
 SLUMBER_PASSWORD
@@ -37,63 +33,47 @@ SLUMBER_PASSWORD
 .. Don't set this automatically, lest we leak something. We are using the dev
    settings in the conf.py, but it's probably a good idea to be safe.
 
-Default: ``test``
-
 The password to use when connecting to the Read the Docs API. Used for hitting the API while building the docs.
 
 USE_SUBDOMAIN
 ---------------
 
-Default: :djangosetting:`USE_SUBDOMAIN`
-
 Whether to use subdomains in URLs on the site, or the Django-served content.
 When used in production, this should be ``True``, as Nginx will serve this content.
 During development and other possible deployments, this might be ``False``.
 
 PRODUCTION_DOMAIN
 ------------------
 
-Default: :djangosetting:`PRODUCTION_DOMAIN`
-
 This is the domain that gets linked to throughout the site when used in production.
 It depends on `USE_SUBDOMAIN`, otherwise it isn't used.
 
 RTD_INTERSPHINX_URL
 -------------------
 
-Default: :djangosetting:`RTD_INTERSPHINX_URL`
-
 This is the domain that is used to fetch the intersphinx inventory file.
 If not set explicitly this is the ``PRODUCTION_DOMAIN``.
 
 DEFAULT_PRIVACY_LEVEL
 ---------------------
 
-Default: :djangosetting:`DEFAULT_PRIVACY_LEVEL`
-
 What privacy projects default to having. Generally set to `public`. Also acts as a proxy setting for blocking certain historically insecure options, like serving generated artifacts directly from the media server.
 
 INDEX_ONLY_LATEST
 -----------------
 
-Default: :djangosetting:`INDEX_ONLY_LATEST`
-
 In search, only index the `latest` version of a Project.
 
 PUBLIC_DOMAIN
 -------------
 
-Default: :djangosetting:`PUBLIC_DOMAIN`
-
 A special domain for serving public documentation.
 If set, public docs will be linked here instead of the `PRODUCTION_DOMAIN`.
 
 
 PUBLIC_DOMAIN_USES_HTTPS
 ------------------------
 
-Default: ``False``
-
 If ``True`` and ``PUBLIC_DOMAIN`` is set, that domain will default to
 serving public documentation over HTTPS. By default, documentation is
 served over HTTP.
@@ -102,16 +82,12 @@ served over HTTP.
 ALLOW_ADMIN
 -----------
 
-Default: :djangosetting:`ALLOW_ADMIN`
-
 Whether to include `django.contrib.admin` in the URL's.
 
 
 RTD_BUILD_MEDIA_STORAGE
 -----------------------
 
-Default: ``readthedocs.builds.storage.BuildMediaFileSystemStorage``
-
 Use this storage class to upload build artifacts to cloud storage (S3, Azure storage).
 This should be a dotted path to the relevant class (eg. ``'path.to.MyBuildMediaStorage'``).
 Your class should mixin :class:`readthedocs.builds.storage.BuildMediaStorageMixin`.
@@ -166,17 +142,13 @@ and the ``settings`` is used for configuring the particular index.
 ES_TASK_CHUNK_SIZE
 ------------------
 
-Default: :djangosetting:`ES_TASK_CHUNK_SIZE`
-
 The maximum number of data send to each elasticsearch indexing celery task.
 This has been used while running ``elasticsearch_reindex`` management command.
 
 
 ES_PAGE_IGNORE_SIGNALS
 ----------------------
 
-Default: ``False``
-
 This settings is used to determine whether to index each page separately into elasticsearch.
 If the setting is ``True``, each ``HTML`` page will not be indexed separately but will be
 indexed by bulk indexing.
@@ -185,11 +157,7 @@ indexed by bulk indexing.
 ELASTICSEARCH_DSL_AUTOSYNC
 --------------------------
 
-Default: ``True``
-
 This setting is used for automatically indexing objects to elasticsearch.
-``False`` by default in development so it is possible to create
-project and build documentations without having elasticsearch.
 
 
 .. _elasticsearch-dsl-py.connections.configure: https://elasticsearch-dsl.readthedocs.io/en/stable/configuration.html#multiple-clusters

docs/doc_extensions.py

@@ -114,7 +114,7 @@ The ``build`` block configures specific aspects of the documentation build.
 build.image
 ```````````
 
-* Default: :djangosetting:`DOCKER_DEFAULT_VERSION`
+* Default: ``latest``
 * Options: ``stable``, ``latest``
 
 The build image to use for specific builds.
@@ -124,8 +124,10 @@ if they want to be on the cutting edge.
 Certain Python versions require a certain build image,
 as defined here:
 
-* ``stable``: :buildpyversions:`stable`
-* ``latest``: :buildpyversions:`latest`
+* ``stable``:
+  ``2``, ``2.7``, ``3``, ``3.5``, ``3.6``, ``3.7``, ``pypy3.5``
+* ``latest``:
+  ``2``, ``2.7``, ``3``, ``3.5``, ``3.6``, ``3.7``, ``3.8``, ``pypy3.5``
 
 .. code-block:: yaml
 
@@ -147,7 +149,7 @@ python.version
 ``````````````
 
 * Default: ``3.7``
-* Options: :buildpyversions:`latest`
+* Options: ``2``, ``2.7``, ``3``, ``3.5``, ``3.6``, ``3.7``, ``3.8``, ``pypy3.5``
 
 This is the version of Python to use when building your documentation.
 If you specify only the major version of Python,

docs/user/config-file/v1.rst

@@ -856,8 +856,10 @@ The Docker image used for building the docs.
 Each image support different Python versions and has different packages installed,
 as defined here:
 
-* `stable <https://github.com/readthedocs/readthedocs-docker-images/tree/releases/5.x>`_: :buildpyversions:`stable`
-* `latest <https://github.com/readthedocs/readthedocs-docker-images/tree/releases/6.x>`_: :buildpyversions:`latest`
+* `stable <https://github.com/readthedocs/readthedocs-docker-images/tree/releases/5.x>`_:
+  ``2``, ``2.7``, ``3``, ``3.5``, ``3.6``, ``3.7``, ``pypy3.5``
+* `latest <https://github.com/readthedocs/readthedocs-docker-images/tree/releases/6.x>`_:
+  ``2``, ``2.7``, ``3``, ``3.5``, ``3.6``, ``3.7``, ``3.8``, ``pypy3.5``
 
 python.version (legacy)
 ```````````````````````

docs/user/config-file/v2.rst

@@ -11,14 +11,14 @@ or reaching out to the administrator of your service.
 Available Flags
 ---------------
 
-``CONDA_APPEND_CORE_REQUIREMENTS``: :featureflags:`CONDA_APPEND_CORE_REQUIREMENTS`
+``CONDA_APPEND_CORE_REQUIREMENTS``: Append Read the Docs core requirements to environment.yml file.
 
 Makes Read the Docs to install all the requirements at once on ``conda create`` step.
 This helps users to pin dependencies on conda and to improve build time.
 
-``DONT_OVERWRITE_SPHINX_CONTEXT``: :featureflags:`DONT_OVERWRITE_SPHINX_CONTEXT`
+``DONT_OVERWRITE_SPHINX_CONTEXT``: Do not overwrite context vars in conf.py with Read the Docs context.
 
-``DONT_CREATE_INDEX``: :featureflags:`DONT_CREATE_INDEX`
+``DONT_CREATE_INDEX``: Do not create index.md or README.rst if the project does not have one.
 
 When Read the Docs detects that your project doesn't have an ``index.md`` or ``README.rst``,
 it auto-generate one for you with instructions about how to proceed.

docs/user/feature-flags.rst

@@ -2,7 +2,7 @@ Embedding Content From Your Documentation
 =========================================
 
 Read the Docs allows you to embed content from any of the projects we host and specific allowed external domains
-(currently, :djangosetting:`RTD_EMBED_API_EXTERNAL_DOMAINS`)
+(currently, ``docs.python.org``, ``docs.scipy.org``, ``docs.sympy.org``, ``numpy.org``)
 This allows reuse of content across sites, making sure the content is always up to date.
 
 There are a number of uses cases for embedding content,

docs/user/guides/embedding-content.rst

@@ -1,7 +1,6 @@
 # Packages required to build docs, independent of application dependencies
 
--r pip.txt
-
+sphinx
 sphinx_rtd_theme==1.2.0rc1
 # Note: Version 3.4.1 of sphinx-tabs requires docutils 0.18 which is yet to be supported by sphinx-rtd-theme
 # Version 3.4.0 has an incompatible Jinja2 version which also blocks sphinx-rtd-theme