Merge tag '6.3.2' into relcorp

Author: humitos

.circleci/config.yml

@@ -47,6 +47,7 @@ jobs:
       - run: tox -e lint
       - run: tox -e docs-lint
       - run: tox -e docs
+      - run: tox -e docs-dev
       - run: tox -e eslint
 
 workflows:

.readthedocs.yml

@@ -16,11 +16,6 @@ build:
     python: "3.8"
 
 search:
-  ignore:
-    # Internal documentation
-    - development/design/*
-    - search.html
-    - 404.html
   ranking:
     # Deprecated content
     api/v1.html: -1

CHANGELOG.rst

@@ -1,3 +1,29 @@
+Version 6.3.2
+-------------
+
+:Date: January 04, 2022
+
+* `@cagatay-y <https://github.com/cagatay-y>`__: Fix broken link in edit-source-links-sphinx.rst (`#8788 <https://github.com/readthedocs/readthedocs.org/pull/8788>`__)
+* `@pyup-bot <https://github.com/pyup-bot>`__: pyup:  Scheduled weekly dependency update for week 52 (`#8787 <https://github.com/readthedocs/readthedocs.org/pull/8787>`__)
+* `@astrojuanlu <https://github.com/astrojuanlu>`__: Cap setuptools even if installed packages are ignored (`#8777 <https://github.com/readthedocs/readthedocs.org/pull/8777>`__)
+* `@pyup-bot <https://github.com/pyup-bot>`__: pyup:  Scheduled weekly dependency update for week 51 (`#8776 <https://github.com/readthedocs/readthedocs.org/pull/8776>`__)
+* `@astrojuanlu <https://github.com/astrojuanlu>`__: Follow up to dev docs split (`#8774 <https://github.com/readthedocs/readthedocs.org/pull/8774>`__)
+* `@stsewd <https://github.com/stsewd>`__: API v3: improve message when using the API on the browser (`#8768 <https://github.com/readthedocs/readthedocs.org/pull/8768>`__)
+* `@stsewd <https://github.com/stsewd>`__: API v3: don't include subproject_of on subprojects (`#8767 <https://github.com/readthedocs/readthedocs.org/pull/8767>`__)
+* `@davidfischer <https://github.com/davidfischer>`__: Use ad client stickybox feature on RTD's own docs (`#8766 <https://github.com/readthedocs/readthedocs.org/pull/8766>`__)
+* `@stsewd <https://github.com/stsewd>`__: API v3: explicitly test with RTD_ALLOW_ORGANIZATIONS=False (`#8765 <https://github.com/readthedocs/readthedocs.org/pull/8765>`__)
+* `@stsewd <https://github.com/stsewd>`__: Update tasks.py (`#8764 <https://github.com/readthedocs/readthedocs.org/pull/8764>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Release 6.3.1 (`#8763 <https://github.com/readthedocs/readthedocs.org/pull/8763>`__)
+* `@humitos <https://github.com/humitos>`__: Update `common/` to latest version (`#8761 <https://github.com/readthedocs/readthedocs.org/pull/8761>`__)
+* `@stsewd <https://github.com/stsewd>`__: Skip slug check when editing an organization (`#8760 <https://github.com/readthedocs/readthedocs.org/pull/8760>`__)
+* `@stsewd <https://github.com/stsewd>`__: Explicit settings for some tests (`#8759 <https://github.com/readthedocs/readthedocs.org/pull/8759>`__)
+* `@ericholscher <https://github.com/ericholscher>`__: Fix EA branding in docs (`#8758 <https://github.com/readthedocs/readthedocs.org/pull/8758>`__)
+* `@pyup-bot <https://github.com/pyup-bot>`__: pyup:  Scheduled weekly dependency update for week 50 (`#8757 <https://github.com/readthedocs/readthedocs.org/pull/8757>`__)
+* `@astrojuanlu <https://github.com/astrojuanlu>`__: Add MyST Markdown examples everywhere (`#8752 <https://github.com/readthedocs/readthedocs.org/pull/8752>`__)
+* `@stsewd <https://github.com/stsewd>`__: Docs: split user and dev docs (`#8751 <https://github.com/readthedocs/readthedocs.org/pull/8751>`__)
+* `@humitos <https://github.com/humitos>`__: Logging: tweaks and minor improvements (`#8736 <https://github.com/readthedocs/readthedocs.org/pull/8736>`__)
+* `@stsewd <https://github.com/stsewd>`__: Audit: test models (`#8495 <https://github.com/readthedocs/readthedocs.org/pull/8495>`__)
+
 Version 6.3.1
 -------------
 

common

@@ -5,43 +5,7 @@
 }
 
 
-/* RTD docs ad placement in the lower right */
-#rtd-stickybox {
-  z-index: 1000;
-  position: fixed;
-  bottom: 20px;
-  right: 20px;
-}
-#rtd-stickybox .ea-content {
-  background: rgba(230, 230, 230);
-}
-#rtd-stickybox .stickybox-hide {
-  cursor: pointer;
-  position: absolute;
-  top: 0.5rem;
-  right: 0.5rem;
-
-  background-color: #fefefe;
-  border: 1px solid #088cdb;
-  border-radius: 50%;
-  color: #088cdb;
-  font-size: 0.75rem;
+/* Center the RTD placement when not wide enough to float */
+#rtd-stickybox-container {
   text-align: center;
-  height: 1rem;
-  width: 1rem;
-}
-
-/* Placement under content on smaller screens/tablets/mobile */
-@media (max-width: 1340px) {
-  #rtd-stickybox {
-    position: static;
-    bottom: 0;
-    right: 0;
-    margin: auto;
-    text-align: center;
-  }
-
-  #rtd-stickybox .stickybox-hide {
-    display: none;
-  }
 }

docs/_static/css/custom.css

@@ -1,4 +1,3 @@
-<div id="rtd-stickybox">
-  <div class="stickybox-hide" onclick="document.querySelector('#rtd-stickybox').remove();">&#215;</div>
-  <div class="raised" data-ea-publisher="readthedocs" data-ea-type="image"></div>
+<div id="rtd-stickybox-container">
+  <div class="raised" data-ea-publisher="readthedocs" data-ea-type="image" data-ea-style="stickybox"></div>
 </div>

docs/_templates/ethicalads.html

@@ -1,3 +1,16 @@
+"""
+Shared Sphinx configuration.
+
+Each docset corresponds to a directory containing several rst/md files,
+sharing this same conf.py file. To build a docset an environment variable
+is used, ``RTD_DOCSET``, values given in the settings are relative to this
+conf.py file, if you want to give a different value for a docset, use the
+``docsets`` dictionary, or if you want to extend the current value,
+use f'{docset}/setting' as value on the setting, for example::
+
+    html_static_path = ['_static', f'{docset}/_static']
+"""
+
 import os
 import sys
 from configparser import RawConfigParser
@@ -14,6 +27,24 @@
 django.setup()
 
 
+# Set here the variables you want for each docset.
+docsets = {
+    'user': {
+        'project': 'Read the Docs user documentation',
+    },
+    'dev': {
+        'project': 'Read the Docs developer documentation',
+    },
+}
+docset = os.environ.get('RTD_DOCSET', 'user')
+if docset not in docsets:
+    print(f'Invalid RTD_DOCSET value: "{docset}"')
+    exit(1)
+
+for k, v in docsets[docset].items():
+    locals()[k] = v
+
+
 def get_version():
     """Return package version from setup.cfg."""
     config = RawConfigParser()
@@ -41,7 +72,6 @@ def get_version():
 templates_path = ['_templates']
 
 master_doc = 'index'
-project = 'Read the Docs'
 copyright = '2010-{}, Read the Docs, Inc & contributors'.format(
     timezone.now().year
 )
@@ -66,6 +96,8 @@ def get_version():
     'jupyterbook': ('https://jupyterbook.org/', None),
     'myst-parser': ('https://myst-parser.readthedocs.io/en/v0.15.1/', None),
     'rst-to-myst': ('https://rst-to-myst.readthedocs.io/en/stable/', None),
+    'rtd': ('https://docs.readthedocs.io/en/stable/', None),
+    'rtd-dev': ('https://dev.readthedocs.io/en/latest/', None),
 }
 myst_enable_extensions = [
     "deflist",
@@ -95,13 +127,13 @@ def get_version():
 language = 'en'
 
 locale_dirs = [
-    'locale/',
+    f'{docset}/locale/',
 ]
 gettext_compact = False
 
 html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
-html_css_files = ['css/custom.css']
+html_static_path = ['_static', f'{docset}/_static']
+html_css_files = ['css/custom.css', 'css/sphinx_prompt_css.css']
 html_js_files = ['js/expand_tabs.js']
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 html_logo = 'img/logo.svg'
@@ -162,4 +194,4 @@ def get_version():
 
 
 def setup(app):
-    app.add_css_file('css/sphinx_prompt_css.css')
+    app.srcdir += '/' + docset

docs/conf.py

@@ -23,7 +23,7 @@ Contributing to development
 
 If you want to deep dive and help out with development on Read the Docs, then
 first get the project installed locally according to the
-:doc:`installation guide </development/install>`. After that is done we
+:doc:`installation guide </install>`. After that is done we
 suggest you have a look at tickets in our issue tracker that are labelled `Good
 First Issue`_. These are meant to be a great way to get a smooth start and
 won't put you in front of the most complex parts of the system.
@@ -38,7 +38,8 @@ They are simply things that are explained.
 If you still didn't find something to work on, search for the `Sprintable`_ label.
 Those tickets are meant to be standalone and can be worked on ad-hoc.
 
-You can read all of our :doc:`/development/index` to understand more the development of Read the Docs. When contributing code, then please follow the standard Contribution Guidelines set forth at `contribution-guide.org`_.
+You can read all of our :doc:`/index` to understand more the development of Read the Docs.
+When contributing code, then please follow the standard Contribution Guidelines set forth at `contribution-guide.org`_.
 
 .. _Feature: https://github.com/readthedocs/readthedocs.org/issues?direction=desc&labels=Feature&page=1&sort=updated&state=open
 .. _Improvement: https://github.com/readthedocs/readthedocs.org/issues?q=is%3Aopen+is%3Aissue+label%3AImprovement
@@ -54,7 +55,7 @@ Contributing to documentation
 Documentation for Read the Docs itself is hosted by Read the Docs at https://docs.readthedocs.io (likely the website you are currently reading).
 
 There are guidelines around writing and formatting documentation for the project.
-For full details, including how to build it, see :doc:`/development/docs`.
+For full details, including how to build it, see :doc:`/docs`.
 
 
 Triaging tickets
@@ -196,7 +197,7 @@ few more at hand to further categorize issues.
     handled during a sprint. They are very focused and encapsulated.
 
 For a full list of available labels and their meanings, see
-:doc:`/development/issue-labels`.
+:doc:`/issue-labels`.
 
 Helpful links for triaging
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/_static/images/design-docs/in-doc-search-ui/in-doc-search-ui-demo.gif renamed to docs/dev/_static/images/design-docs/in-doc-search-ui/in-doc-search-ui-demo.gif

@@ -7,7 +7,7 @@ time and design skills to Read the Docs? That's
 a few features available to ease the process of
 working with Read the Doc's CSS and static assets.
 
-To start, you should follow the :doc:`/development/install` instructions
+To start, you should follow the :doc:`/install` instructions
 to get a working copy of the Read the Docs repository locally.
 
 .. TODO: update to match the new ext-theme

docs/_static/images/development/bitbucket-oauth-setup.png renamed to docs/dev/_static/images/development/bitbucket-oauth-setup.png

@@ -23,7 +23,7 @@ and remove some quirkiness that makes it hard to maintain and difficult to use.
 Current implementation
 ----------------------
 
-The current implementation of the API is partially documented in :doc:`/guides/embedding-content`.
+The current implementation of the API is partially documented in :doc:`rtd:guides/embedding-content`.
 It has some known problems:
 
 * There are different ways of querying the API: ``?url=`` (generic) and ``?doc=`` (relies on Sphinx's specific concept)

docs/development/architecture.rst renamed to docs/dev/architecture.rst

@@ -18,9 +18,9 @@ This is a GSoC'19 project.
 
 The final result may look something like this:
 
-.. figure:: ../../_static/images/design-docs/in-doc-search-ui/in-doc-search-ui-demo.gif
+.. figure:: /_static/images/design-docs/in-doc-search-ui/in-doc-search-ui-demo.gif
     :align: center
-    :target: ../../_static/images/design-docs/in-doc-search-ui/in-doc-search-ui-demo.gif
+    :target: /_static/images/design-docs/in-doc-search-ui/in-doc-search-ui-demo.gif
 
     Short demo
 

docs/code-of-conduct.rst renamed to docs/dev/code-of-conduct.rst

@@ -112,7 +112,7 @@ Note that this dictionary is injected under the main key `readthedocs`:
    so it's your responsibility to use this context in a proper way.
 
    In case you want *fresh data* at the moment of reading your documentation,
-   you should consider using the :doc:`Read the Docs Public API </api/index>` via Javascript.
+   you should consider using the :doc:`Read the Docs Public API <rtd:api/index>` via Javascript.
 
 
 Using Read the Docs context in your theme

docs/contribute.rst renamed to docs/dev/contribute.rst

@@ -3,7 +3,8 @@ Building and Contributing to Documentation
 
 As one might expect,
 the documentation for Read the Docs is built using Sphinx and hosted on Read the Docs.
-The docs are kept in the ``docs/`` directory at the top of the source tree.
+The docs are kept in the ``docs/`` directory at the top of the source tree,
+and are divided into developer and user-facing documentation.
 
 Contributing through the Github UI
 ----------------------------------
@@ -51,11 +52,20 @@ you may want to verify those changes locally before pushing upstream.
 
 #. build the documents
 
+   To build the user-facing documentation:
+
    .. code-block:: console
 
       (.venv) $ cd docs
       (.venv) $ make livehtml
 
+   To build the developer documentation:
+
+   .. code-block:: console
+
+      (.venv) $ cd docs
+      (.venv) $ RTD_DOCSET=dev make livehtml
+
 #. the documents will be available at http://127.0.0.1:4444/ and will rebuild each time you edit and save a file.
 
 Guidelines

docs/development/design.rst renamed to docs/dev/design.rst

@@ -55,7 +55,7 @@ in.
 Getting Started
 ---------------
 
-You will need to follow our :doc:`guide to install a development Read the Docs instance </development/install>` first.
+You will need to follow our :doc:`guide to install a development Read the Docs instance </install>` first.
 
 The sources for our bundles are found in the per-application path
 ``static-src``, which has the same directory structure as ``static``. Files in

docs/development/design/apiv3.rst renamed to docs/dev/design/apiv3.rst

@@ -0,0 +1,30 @@
+Read the Docs developer documentation
+=====================================
+
+Documentation for running your own local version of Read the Docs for development,
+or taking the open source Read the Docs codebase for your own custom installation.
+
+.. toctree::
+   :caption: General
+   :maxdepth: 1
+
+   contribute
+   code-of-conduct
+   issue-labels
+   roadmap
+   design/index
+
+.. toctree::
+   :caption: Development
+   :maxdepth: 1
+
+   install
+   design
+   docs
+   front-end
+   i18n
+   search
+   search-integration
+   settings
+   tests
+   architecture

docs/development/design/build-images.rst renamed to docs/dev/design/build-images.rst

@@ -199,21 +199,21 @@ debugging currently.
 Configuring connected accounts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These are optional steps to setup the :doc:`connected accounts </connected-accounts>`
+These are optional steps to setup the :doc:`connected accounts <rtd:connected-accounts>`
 (GitHub, GitLab, and BitBucket) in your development environment.
 This will allow you to login to your local development instance
 using your GitHub, Bitbucket, or GitLab credentials
 and this makes the process of importing repositories easier.
 
 However, because these services will not be able to connect back to your local development instance,
-:doc:`incoming webhooks </integrations>` will not function correctly.
+:doc:`incoming webhooks <rtd:integrations>` will not function correctly.
 For some services, the webhooks will fail to be added when the repository is imported.
 For others, the webhook will simply fail to connect when there are new commits to the repository.
 
-.. figure:: ../_static/images/development/bitbucket-oauth-setup.png
+.. figure:: /_static/images/development/bitbucket-oauth-setup.png
     :align: center
     :figwidth: 80%
-    :target: ../_static/images/development/bitbucket-oauth-setup.png
+    :target: /_static/images/development/bitbucket-oauth-setup.png
 
     Configuring an OAuth consumer for local development on Bitbucket
 

docs/development/design/embed-api.rst renamed to docs/dev/design/embed-api.rst

@@ -1,7 +1,7 @@
 Server Side Search Integration
 ==============================
 
-Read the Docs provides :doc:`server side search (SSS) </server-side-search>`
+Read the Docs provides :doc:`server side search (SSS) <rtd:server-side-search>`
 in replace of the default search engine of your site.
 To accomplish this, Read the Docs parses the content directly from your HTML pages [*]_.
 
@@ -309,7 +309,7 @@ Supporting more themes and static site generators
 -------------------------------------------------
 
 Currently, Read the Docs supports building documentation from
-:doc:`Sphinx </intro/getting-started-with-sphinx>` and :doc:`MkDocs </intro/getting-started-with-mkdocs>`.
+:doc:`Sphinx <rtd:intro/getting-started-with-sphinx>` and :doc:`MkDocs <rtd:intro/getting-started-with-mkdocs>`.
 All themes that follow these conventions should work as expected.
 If you think other generators or other conventions should be supported,
 or content that should be ignored or have an especial treatment,

docs/development/design/in-doc-search-ui.rst renamed to docs/dev/design/in-doc-search-ui.rst

@@ -9,7 +9,7 @@ Currently we are using `Elasticsearch 6.3`_.
 Local Development Configuration
 -------------------------------
 
-Elasticsearch is installed and run as part of the :doc:`development installation guide </development/install>`.
+Elasticsearch is installed and run as part of the :doc:`development installation guide </install>`.
 
 Indexing into Elasticsearch
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^