Merge remote-tracking branch 'origin' into use-django-storages

Author: dogukanteber

.circleci/config.yml

@@ -10,6 +10,7 @@ jobs:
         name: search
         environment:
           discovery.type: single-node
+          ES_JAVA_OPTS: -Xms750m -Xmx750m
     steps:
       - checkout
       - run: git submodule sync
@@ -47,6 +48,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:

.github/CODEOWNERS

@@ -1,3 +1,3 @@
 *       @readthedocs/backend
 
-docs/*  @readthedocs/advocacy
+/docs/  @readthedocs/advocacy

.github/ISSUE_TEMPLATE/bug.md

@@ -5,9 +5,9 @@ about: Report some incorrect or unexpected behavior
 
 ## Details
 
-* Read the Docs project URL:
-* Build URL (if applicable):
-* Read the Docs username (if applicable):
+* Read the Docs project URL: https://readthedocs.org/projects/{your_project_slug}/
+* Build URL (if applicable): https://readthedocs.org/projects/{your_project_slug}/builds/{build_id}/
+* Read the Docs username (if applicable): https://readthedocs.org/profiles/{your_rtd_username}/
 
 ## Expected Result
 

.readthedocs.yml

@@ -16,15 +16,10 @@ build:
     python: "3.8"
 
 search:
-  ignore:
-    # Internal documentation
-    - development/design/*
-    - search.html
-    - 404.html
   ranking:
     # Deprecated content
     api/v1.html: -1
-    config-file/v1.html: -1
+    config-file/v1.html: -5
 
     # Useful content, but not something we want most users finding
     changelog.html: -6

CHANGELOG.rst

@@ -50,6 +50,7 @@ RUN ln -s /usr/bin/python3 /usr/bin/python
 WORKDIR /tmp
 
 COPY requirements/pip.txt pip.txt
+COPY requirements/debug.txt debug.txt
 COPY requirements/docker.txt docker.txt
 RUN pip3 install --no-cache-dir -r docker.txt
 

common

@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = _build/$(RTD_DOCSET)
 
 # Do not use local Django settings during the docs build
 export DJANGO_SETTINGS_SKIP_LOCAL = True

dockerfiles/Dockerfile

@@ -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/Makefile

@@ -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/_static/css/custom.css

@@ -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,20 +127,26 @@ 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'
 html_theme_options = {
     'logo_only': True,
     'display_version': False,
 }
+html_context = {
+    # Fix the "edit on" links.
+    # TODO: remove once we support different rtd config
+    # files per project.
+    'conf_py_path': f'/docs/{docset}/',
+}
 
 hoverxref_auto_ref = True
 hoverxref_domains = ['py']
@@ -162,4 +200,4 @@ def get_version():
 
 
 def setup(app):
-    app.add_css_file('css/sphinx_prompt_css.css')
+    app.srcdir += '/' + docset

docs/_templates/ethicalads.html

@@ -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/choosing-a-site.rst

@@ -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/conf.py

@@ -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/_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

@@ -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
 
@@ -49,7 +49,7 @@ Existing Search Implementation
 
 We have a detailed documentation explaining the underlying architecture of our search backend
 and how we index documents to our Elasticsearch index.
-You can read about it :doc:`here <../search>`.
+You can read about it :doc:`here </server-side-search>`.
 
 
 Proposed Architecture for In-Doc Search UI

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

@@ -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/development/architecture.rst renamed to docs/dev/architecture.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/code-of-conduct.rst renamed to docs/dev/code-of-conduct.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