readthedocs · astrojuanlu · Dec 20, 2021 · Dec 7, 2021 · Dec 7, 2021 · Dec 8, 2021
diff --git a/.circleci/config.yml b/.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:

diff --git a/.readthedocs.yml b/.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

diff --git a/docs/conf.py b/docs/conf.py
@@ -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/stable/', None),
-    'rtd-dev': ('https://dev.readthedocs.io/en/stable/', None),
+    'rtd-dev': ('https://dev.readthedocs.io/en/separate-dev-docs/', None),
-    'rtd-dev': ('https://dev.readthedocs.io/en/stable/', None),
+    'rtd-dev': ('https://dev.readthedocs.io/en/separate-dev-docs/', 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
diff --git a/...n-doc-search-ui/in-doc-search-ui-demo.gif → ...n-doc-search-ui/in-doc-search-ui-demo.gif b/...n-doc-search-ui/in-doc-search-ui-demo.gif → ...n-doc-search-ui/in-doc-search-ui-demo.gif
diff --git a/...ges/development/bitbucket-oauth-setup.png → ...ges/development/bitbucket-oauth-setup.png b/...ges/development/bitbucket-oauth-setup.png → ...ges/development/bitbucket-oauth-setup.png
diff --git a/docs/development/architecture.rst → docs/dev/architecture.rst b/docs/development/architecture.rst → docs/dev/architecture.rst
diff --git a/docs/code-of-conduct.rst → docs/dev/code-of-conduct.rst b/docs/code-of-conduct.rst → docs/dev/code-of-conduct.rst
diff --git a/docs/contribute.rst → docs/dev/contribute.rst b/docs/contribute.rst → docs/dev/contribute.rst
@@ -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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/development/design.rst → docs/dev/design.rst b/docs/development/design.rst → docs/dev/design.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

diff --git a/docs/development/design/apiv3.rst → docs/dev/design/apiv3.rst b/docs/development/design/apiv3.rst → docs/dev/design/apiv3.rst
diff --git a/docs/development/design/build-images.rst → docs/dev/design/build-images.rst b/docs/development/design/build-images.rst → docs/dev/design/build-images.rst
diff --git a/docs/development/design/embed-api.rst → docs/dev/design/embed-api.rst b/docs/development/design/embed-api.rst → docs/dev/design/embed-api.rst
@@ -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)

diff --git a/docs/development/design/in-doc-search-ui.rst → docs/dev/design/in-doc-search-ui.rst b/docs/development/design/in-doc-search-ui.rst → docs/dev/design/in-doc-search-ui.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
 

diff --git a/docs/development/design/index.rst → docs/dev/design/index.rst b/docs/development/design/index.rst → docs/dev/design/index.rst
diff --git a/.../development/design/new-sphinx-guides.rst → docs/dev/design/new-sphinx-guides.rst b/.../development/design/new-sphinx-guides.rst → docs/dev/design/new-sphinx-guides.rst
diff --git a/docs/development/design/organizations.rst → docs/dev/design/organizations.rst b/docs/development/design/organizations.rst → docs/dev/design/organizations.rst
diff --git a/docs/development/design/pr-builder.rst → docs/dev/design/pr-builder.rst b/docs/development/design/pr-builder.rst → docs/dev/design/pr-builder.rst
diff --git a/docs/development/design/privacy-levels.rst → docs/dev/design/privacy-levels.rst b/docs/development/design/privacy-levels.rst → docs/dev/design/privacy-levels.rst
diff --git a/...ent/design/refactor-remote-repository.rst → ...dev/design/refactor-remote-repository.rst b/...ent/design/refactor-remote-repository.rst → ...dev/design/refactor-remote-repository.rst
diff --git a/docs/development/design/system-packages.rst → docs/dev/design/system-packages.rst b/docs/development/design/system-packages.rst → docs/dev/design/system-packages.rst
diff --git a/docs/development/design/theme-context.rst → docs/dev/design/theme-context.rst b/docs/development/design/theme-context.rst → docs/dev/design/theme-context.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

diff --git a/docs/development/design/yaml-file.rst → docs/dev/design/yaml-file.rst b/docs/development/design/yaml-file.rst → docs/dev/design/yaml-file.rst
diff --git a/docs/development/docs.rst → docs/dev/docs.rst b/docs/development/docs.rst → docs/dev/docs.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

diff --git a/docs/development/front-end.rst → docs/dev/front-end.rst b/docs/development/front-end.rst → docs/dev/front-end.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

diff --git a/docs/development/i18n.rst → docs/dev/i18n.rst b/docs/development/i18n.rst → docs/dev/i18n.rst
diff --git a/docs/img/details_link.png → docs/dev/img/details_link.png b/docs/img/details_link.png → docs/dev/img/details_link.png
diff --git a/docs/img/headers.png → docs/dev/img/headers.png b/docs/img/headers.png → docs/dev/img/headers.png
diff --git a/docs/dev/index.rst b/docs/dev/index.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
diff --git a/docs/development/install.rst → docs/dev/install.rst b/docs/development/install.rst → docs/dev/install.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
 

diff --git a/docs/development/issue-labels.rst → docs/dev/issue-labels.rst b/docs/development/issue-labels.rst → docs/dev/issue-labels.rst
diff --git a/docs/roadmap.rst → docs/dev/roadmap.rst b/docs/roadmap.rst → docs/dev/roadmap.rst
diff --git a/docs/development/search-integration.rst → docs/dev/search-integration.rst b/docs/development/search-integration.rst → docs/dev/search-integration.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,

diff --git a/docs/development/search.rst → docs/dev/search.rst b/docs/development/search.rst → docs/dev/search.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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/development/settings.rst → docs/dev/settings.rst b/docs/development/settings.rst → docs/dev/settings.rst
diff --git a/docs/development/tests.rst → docs/dev/tests.rst b/docs/development/tests.rst → docs/dev/tests.rst
diff --git a/docs/development/index.rst b/docs/development/index.rst
diff --git a/docs/.tx/config → docs/user/.tx/config b/docs/.tx/config → docs/user/.tx/config
diff --git a/docs/_static/dmca/takedown-template.txt → docs/user/_static/dmca/takedown-template.txt b/docs/_static/dmca/takedown-template.txt → docs/user/_static/dmca/takedown-template.txt
diff --git a/...static/images/first-steps/admin-panel.png → ...static/images/first-steps/admin-panel.png b/...static/images/first-steps/admin-panel.png → ...static/images/first-steps/admin-panel.png
diff --git a/...mages/first-steps/import-a-repository.png → ...mages/first-steps/import-a-repository.png b/...mages/first-steps/import-a-repository.png → ...mages/first-steps/import-a-repository.png
diff --git a/...images/first-steps/mkdocs-hello-world.png → ...images/first-steps/mkdocs-hello-world.png b/...images/first-steps/mkdocs-hello-world.png → ...images/first-steps/mkdocs-hello-world.png
diff --git a/...images/first-steps/sphinx-hello-world.png → ...images/first-steps/sphinx-hello-world.png b/...images/first-steps/sphinx-hello-world.png → ...images/first-steps/sphinx-hello-world.png
diff --git a/.../images/github-build-status-reporting.gif → .../images/github-build-status-reporting.gif b/.../images/github-build-status-reporting.gif → .../images/github-build-status-reporting.gif
diff --git a/...tatic/images/google-analytics-options.png → ...tatic/images/google-analytics-options.png b/...tatic/images/google-analytics-options.png → ...tatic/images/google-analytics-options.png
diff --git a/...ages/guides/example-notebook-rendered.png → ...ages/guides/example-notebook-rendered.png b/...ages/guides/example-notebook-rendered.png → ...ages/guides/example-notebook-rendered.png
diff --git a/...static/images/guides/example-notebook.png → ...static/images/guides/example-notebook.png b/...static/images/guides/example-notebook.png → ...static/images/guides/example-notebook.png
diff --git a/...atic/images/guides/flyout-overwhelmed.png → ...atic/images/guides/flyout-overwhelmed.png b/...atic/images/guides/flyout-overwhelmed.png → ...atic/images/guides/flyout-overwhelmed.png
diff --git a/...s/guides/google-search-engine-results.png → ...s/guides/google-search-engine-results.png b/...s/guides/google-search-engine-results.png → ...s/guides/google-search-engine-results.png
diff --git a/...tic/images/guides/jupyterlab-metadata.png → ...tic/images/guides/jupyterlab-metadata.png b/...tic/images/guides/jupyterlab-metadata.png → ...tic/images/guides/jupyterlab-metadata.png
diff --git a/...s/guides/jupyterlab-save-widget-state.png → ...s/guides/jupyterlab-save-widget-state.png b/...s/guides/jupyterlab-save-widget-state.png → ...s/guides/jupyterlab-save-widget-state.png
diff --git a/...mages/guides/sphinx-hoverxref-example.png → ...mages/guides/sphinx-hoverxref-example.png b/...mages/guides/sphinx-hoverxref-example.png → ...mages/guides/sphinx-hoverxref-example.png
diff --git a/...tatic/images/guides/thumbnail-gallery.png → ...tatic/images/guides/thumbnail-gallery.png b/...tatic/images/guides/thumbnail-gallery.png → ...tatic/images/guides/thumbnail-gallery.png
diff --git a/docs/_static/images/guides/widget-html.gif → ...ser/_static/images/guides/widget-html.gif b/docs/_static/images/guides/widget-html.gif → ...ser/_static/images/guides/widget-html.gif
diff --git a/docs/_static/images/logout-button.png → docs/user/_static/images/logout-button.png b/docs/_static/images/logout-button.png → docs/user/_static/images/logout-button.png
diff --git a/.../_static/images/search-analytics-demo.png → .../_static/images/search-analytics-demo.png b/.../_static/images/search-analytics-demo.png → .../_static/images/search-analytics-demo.png
diff --git a/..._static/images/traffic-analytics-demo.png → ..._static/images/traffic-analytics-demo.png b/..._static/images/traffic-analytics-demo.png → ..._static/images/traffic-analytics-demo.png
diff --git a/...tatic/images/tutorial/active-versions.png → ...tatic/images/tutorial/active-versions.png b/...tatic/images/tutorial/active-versions.png → ...tatic/images/tutorial/active-versions.png
diff --git a/...tatic/images/tutorial/build-python3.8.png → ...tatic/images/tutorial/build-python3.8.png b/...tatic/images/tutorial/build-python3.8.png → ...tatic/images/tutorial/build-python3.8.png
diff --git a/...atic/images/tutorial/flyout-downloads.png → ...atic/images/tutorial/flyout-downloads.png b/...atic/images/tutorial/flyout-downloads.png → ...atic/images/tutorial/flyout-downloads.png
diff --git a/docs/_static/images/tutorial/gh-edit.png → .../user/_static/images/tutorial/gh-edit.png b/docs/_static/images/tutorial/gh-edit.png → .../user/_static/images/tutorial/gh-edit.png
diff --git a/docs/_static/images/tutorial/gh-pr-build.png → ...r/_static/images/tutorial/gh-pr-build.png b/docs/_static/images/tutorial/gh-pr-build.png → ...r/_static/images/tutorial/gh-pr-build.png
diff --git a/.../images/tutorial/github-authorization.png → .../images/tutorial/github-authorization.png b/.../images/tutorial/github-authorization.png → .../images/tutorial/github-authorization.png
diff --git a/...tatic/images/tutorial/github-template.png → ...tatic/images/tutorial/github-template.png b/...tatic/images/tutorial/github-template.png → ...tatic/images/tutorial/github-template.png
diff --git a/...tic/images/tutorial/inactive-versions.png → ...tic/images/tutorial/inactive-versions.png b/...tic/images/tutorial/inactive-versions.png → ...tic/images/tutorial/inactive-versions.png
diff --git a/...c/images/tutorial/old-version-warning.png → ...c/images/tutorial/old-version-warning.png b/...c/images/tutorial/old-version-warning.png → ...c/images/tutorial/old-version-warning.png
diff --git a/...c/images/tutorial/rtd-empty-dashboard.png → ...c/images/tutorial/rtd-empty-dashboard.png b/...c/images/tutorial/rtd-empty-dashboard.png → ...c/images/tutorial/rtd-empty-dashboard.png
diff --git a/...tatic/images/tutorial/rtd-first-light.png → ...tatic/images/tutorial/rtd-first-light.png b/...tatic/images/tutorial/rtd-first-light.png → ...tatic/images/tutorial/rtd-first-light.png
diff --git a/...s/tutorial/rtd-first-successful-build.png → ...s/tutorial/rtd-first-successful-build.png b/...s/tutorial/rtd-first-successful-build.png → ...s/tutorial/rtd-first-successful-build.png
diff --git a/...c/images/tutorial/rtd-import-projects.gif → ...c/images/tutorial/rtd-import-projects.gif b/...c/images/tutorial/rtd-import-projects.gif → ...c/images/tutorial/rtd-import-projects.gif
diff --git a/...atic/images/tutorial/rtd-project-home.png → ...atic/images/tutorial/rtd-project-home.png b/...atic/images/tutorial/rtd-project-home.png → ...atic/images/tutorial/rtd-project-home.png
diff --git a/...mages/tutorial/search-analytics-terms.png → ...mages/tutorial/search-analytics-terms.png b/...mages/tutorial/search-analytics-terms.png → ...mages/tutorial/search-analytics-terms.png
diff --git a/...mages/tutorial/traffic-analytics-plot.png → ...mages/tutorial/traffic-analytics-plot.png b/...mages/tutorial/traffic-analytics-plot.png → ...mages/tutorial/traffic-analytics-plot.png
diff --git a/docs/_static/images/webhooks-activity.png → ...user/_static/images/webhooks-activity.png b/docs/_static/images/webhooks-activity.png → ...user/_static/images/webhooks-activity.png
diff --git a/docs/_static/images/webhooks-events.png → docs/user/_static/images/webhooks-events.png b/docs/_static/images/webhooks-events.png → docs/user/_static/images/webhooks-events.png
diff --git a/docs/_static/images/webhooks-payload.png → .../user/_static/images/webhooks-payload.png b/docs/_static/images/webhooks-payload.png → .../user/_static/images/webhooks-payload.png
diff --git a/docs/_static/images/webhooks-secret.png → docs/user/_static/images/webhooks-secret.png b/docs/_static/images/webhooks-secret.png → docs/user/_static/images/webhooks-secret.png
diff --git a/docs/_static/security/pgpkey.txt → docs/user/_static/security/pgpkey.txt b/docs/_static/security/pgpkey.txt → docs/user/_static/security/pgpkey.txt
diff --git a/docs/abandoned-projects.rst → docs/user/abandoned-projects.rst b/docs/abandoned-projects.rst → docs/user/abandoned-projects.rst
diff --git a/docs/about.rst → docs/user/about.rst b/docs/about.rst → docs/user/about.rst
@@ -16,7 +16,7 @@ We have built something that we expect to last a long time,
 and we are able to make decisions based only on the best interest of our community and customers.
 
 All of the source code for Read the Docs is open source.
-You are welcome to :doc:`contribute </contribute>` the features you want or run your own instance.
+You are welcome to :doc:`contribute <rtd-dev:contribute>` the features you want or run your own instance.
 We should note that we generally only support our hosted versions as a matter of :doc:`our philosophy </open-source-philosophy>`.
 
 We owe a great deal to the open source community that we are a part of,

diff --git a/docs/advertising/ad-blocking.rst → docs/user/advertising/ad-blocking.rst b/docs/advertising/ad-blocking.rst → docs/user/advertising/ad-blocking.rst
diff --git a/docs/advertising/ad-customization.rst → docs/user/advertising/ad-customization.rst b/docs/advertising/ad-customization.rst → docs/user/advertising/ad-customization.rst
diff --git a/docs/advertising/advertising-details.rst → .../user/advertising/advertising-details.rst b/docs/advertising/advertising-details.rst → .../user/advertising/advertising-details.rst
diff --git a/docs/advertising/ethical-advertising.rst → .../user/advertising/ethical-advertising.rst b/docs/advertising/ethical-advertising.rst → .../user/advertising/ethical-advertising.rst
diff --git a/docs/advertising/index.rst → docs/user/advertising/index.rst b/docs/advertising/index.rst → docs/user/advertising/index.rst
diff --git a/docs/analytics.rst → docs/user/analytics.rst b/docs/analytics.rst → docs/user/analytics.rst
diff --git a/docs/api/index.rst → docs/user/api/index.rst b/docs/api/index.rst → docs/user/api/index.rst
diff --git a/docs/api/v1.rst → docs/user/api/v1.rst b/docs/api/v1.rst → docs/user/api/v1.rst
diff --git a/docs/api/v2.rst → docs/user/api/v2.rst b/docs/api/v2.rst → docs/user/api/v2.rst
diff --git a/docs/api/v3.rst → docs/user/api/v3.rst b/docs/api/v3.rst → docs/user/api/v3.rst
diff --git a/docs/automatic-redirects.rst → docs/user/automatic-redirects.rst b/docs/automatic-redirects.rst → docs/user/automatic-redirects.rst
diff --git a/docs/automation-rules.rst → docs/user/automation-rules.rst b/docs/automation-rules.rst → docs/user/automation-rules.rst
diff --git a/docs/badges.rst → docs/user/badges.rst b/docs/badges.rst → docs/user/badges.rst
diff --git a/docs/build-notifications.rst → docs/user/build-notifications.rst b/docs/build-notifications.rst → docs/user/build-notifications.rst
diff --git a/docs/builds.rst → docs/user/builds.rst b/docs/builds.rst → docs/user/builds.rst
diff --git a/docs/changelog.rst → docs/user/changelog.rst b/docs/changelog.rst → docs/user/changelog.rst
@@ -1,7 +1,7 @@
 Changelog
 =========
 
-.. include:: ../CHANGELOG.rst
+.. include:: ../../CHANGELOG.rst
 
 Previous releases
 -----------------

diff --git a/docs/choosing-a-site.rst → docs/user/choosing-a-site.rst b/docs/choosing-a-site.rst → docs/user/choosing-a-site.rst
diff --git a/docs/commercial/index.rst → docs/user/commercial/index.rst b/docs/commercial/index.rst → docs/user/commercial/index.rst
diff --git a/docs/commercial/organizations.rst → docs/user/commercial/organizations.rst b/docs/commercial/organizations.rst → docs/user/commercial/organizations.rst
diff --git a/docs/commercial/privacy-level.rst → docs/user/commercial/privacy-level.rst b/docs/commercial/privacy-level.rst → docs/user/commercial/privacy-level.rst
diff --git a/docs/commercial/sharing.rst → docs/user/commercial/sharing.rst b/docs/commercial/sharing.rst → docs/user/commercial/sharing.rst
diff --git a/docs/commercial/single-sign-on.rst → docs/user/commercial/single-sign-on.rst b/docs/commercial/single-sign-on.rst → docs/user/commercial/single-sign-on.rst
diff --git a/docs/config-file/index.rst → docs/user/config-file/index.rst b/docs/config-file/index.rst → docs/user/config-file/index.rst
diff --git a/docs/config-file/v1.rst → docs/user/config-file/v1.rst b/docs/config-file/v1.rst → docs/user/config-file/v1.rst
diff --git a/docs/config-file/v2.rst → docs/user/config-file/v2.rst b/docs/config-file/v2.rst → docs/user/config-file/v2.rst
diff --git a/docs/connected-accounts.rst → docs/user/connected-accounts.rst b/docs/connected-accounts.rst → docs/user/connected-accounts.rst
diff --git a/docs/custom_domains.rst → docs/user/custom_domains.rst b/docs/custom_domains.rst → docs/user/custom_domains.rst
diff --git a/docs/dmca/index.rst → docs/user/dmca/index.rst b/docs/dmca/index.rst → docs/user/dmca/index.rst
diff --git a/docs/downloadable-documentation.rst → docs/user/downloadable-documentation.rst b/docs/downloadable-documentation.rst → docs/user/downloadable-documentation.rst
diff --git a/docs/environment-variables.rst → docs/user/environment-variables.rst b/docs/environment-variables.rst → docs/user/environment-variables.rst
diff --git a/docs/faq.rst → docs/user/faq.rst b/docs/faq.rst → docs/user/faq.rst
diff --git a/docs/feature-flags.rst → docs/user/feature-flags.rst b/docs/feature-flags.rst → docs/user/feature-flags.rst
diff --git a/docs/features.rst → docs/user/features.rst b/docs/features.rst → docs/user/features.rst
@@ -82,7 +82,7 @@ Read the Docs cares deeply about our customers and our community.
 As part of that commitment,
 all of the source code for Read the Docs is open source.
 This means there's no vendor lock-in,
-and you are welcome to :doc:`contribute </contribute>` the features you want or run your own instance.
+and you are welcome to :doc:`contribute <rtd-dev:contribute>` the features you want or run your own instance.
 
 Our bootstrapped company is owned and controlled by the founders,
 and fully funded by our customers and advertisers.

diff --git a/docs/glossary.rst → docs/user/glossary.rst b/docs/glossary.rst → docs/user/glossary.rst
diff --git a/docs/gsoc.rst → docs/user/gsoc.rst b/docs/gsoc.rst → docs/user/gsoc.rst
@@ -33,10 +33,10 @@ the more likely we are to choose your application!
 Getting Started
 ---------------
 
-The :doc:`/development/install` doc is probably the best place to get going.
+The :doc:`rtd-dev:install` doc is probably the best place to get going.
 It will walk you through getting a basic environment for Read the Docs setup.
 
-Then you can look through our :doc:`/contribute` doc for information on how to get started contributing to RTD.
+Then you can look through our :doc:`rtd-dev:contribute` doc for information on how to get started contributing to RTD.
 
 People who have a history of submitting pull requests will be prioritized in our Summer of Code selection process.
 

diff --git a/docs/guides/adding-custom-css.rst → docs/user/guides/adding-custom-css.rst b/docs/guides/adding-custom-css.rst → docs/user/guides/adding-custom-css.rst
diff --git a/docs/guides/administrators.rst → docs/user/guides/administrators.rst b/docs/guides/administrators.rst → docs/user/guides/administrators.rst
diff --git a/docs/guides/advanced-search.rst → docs/user/guides/advanced-search.rst b/docs/guides/advanced-search.rst → docs/user/guides/advanced-search.rst
@@ -5,9 +5,6 @@ Read the Docs uses :doc:`/server-side-search` to power our search.
 This guide explains how to add a "search as you type" feature to your documentation,
 and how to use advanced query syntax to get more accurate results.
 
-You can find information on the search architecture and how we index documents in our
-:doc:`Search </development/search>` docs.
-
 .. contents:: Table of contents
    :local:
    :backlinks: none

diff --git a/docs/guides/authors.rst → docs/user/guides/authors.rst b/docs/guides/authors.rst → docs/user/guides/authors.rst
diff --git a/...guides/build-using-too-many-resources.rst → ...guides/build-using-too-many-resources.rst b/...guides/build-using-too-many-resources.rst → ...guides/build-using-too-many-resources.rst
diff --git a/docs/guides/conda.rst → docs/user/guides/conda.rst b/docs/guides/conda.rst → docs/user/guides/conda.rst
diff --git a/.../guides/cross-referencing-with-sphinx.rst → .../guides/cross-referencing-with-sphinx.rst b/.../guides/cross-referencing-with-sphinx.rst → .../guides/cross-referencing-with-sphinx.rst
diff --git a/docs/guides/deprecating-content.rst → docs/user/guides/deprecating-content.rst b/docs/guides/deprecating-content.rst → docs/user/guides/deprecating-content.rst
diff --git a/docs/guides/developers.rst → docs/user/guides/developers.rst b/docs/guides/developers.rst → docs/user/guides/developers.rst
diff --git a/docs/guides/edit-source-links-sphinx.rst → .../user/guides/edit-source-links-sphinx.rst b/docs/guides/edit-source-links-sphinx.rst → .../user/guides/edit-source-links-sphinx.rst
diff --git a/docs/guides/embedding-content.rst → docs/user/guides/embedding-content.rst b/docs/guides/embedding-content.rst → docs/user/guides/embedding-content.rst
diff --git a/docs/guides/hiding-a-version.rst → docs/user/guides/hiding-a-version.rst b/docs/guides/hiding-a-version.rst → docs/user/guides/hiding-a-version.rst
diff --git a/...guides/importing-private-repositories.rst → ...guides/importing-private-repositories.rst b/...guides/importing-private-repositories.rst → ...guides/importing-private-repositories.rst
diff --git a/docs/guides/index.rst → docs/user/guides/index.rst b/docs/guides/index.rst → docs/user/guides/index.rst
diff --git a/docs/guides/intersphinx.rst → docs/user/guides/intersphinx.rst b/docs/guides/intersphinx.rst → docs/user/guides/intersphinx.rst
diff --git a/docs/guides/jupyter.rst → docs/user/guides/jupyter.rst b/docs/guides/jupyter.rst → docs/user/guides/jupyter.rst
diff --git a/docs/guides/manage-translations-sphinx.rst → ...ser/guides/manage-translations-sphinx.rst b/docs/guides/manage-translations-sphinx.rst → ...ser/guides/manage-translations-sphinx.rst
diff --git a/docs/guides/migrate-rest-myst.md → docs/user/guides/migrate-rest-myst.md b/docs/guides/migrate-rest-myst.md → docs/user/guides/migrate-rest-myst.md
diff --git a/docs/guides/pdf-non-ascii-languages.rst → docs/user/guides/pdf-non-ascii-languages.rst b/docs/guides/pdf-non-ascii-languages.rst → docs/user/guides/pdf-non-ascii-languages.rst
diff --git a/docs/guides/poetry.rst → docs/user/guides/poetry.rst b/docs/guides/poetry.rst → docs/user/guides/poetry.rst
diff --git a/docs/guides/private-python-packages.rst → docs/user/guides/private-python-packages.rst b/docs/guides/private-python-packages.rst → docs/user/guides/private-python-packages.rst
diff --git a/docs/guides/private-submodules.rst → docs/user/guides/private-submodules.rst b/docs/guides/private-submodules.rst → docs/user/guides/private-submodules.rst
diff --git a/docs/guides/remove-edit-buttons.rst → docs/user/guides/remove-edit-buttons.rst b/docs/guides/remove-edit-buttons.rst → docs/user/guides/remove-edit-buttons.rst
diff --git a/docs/guides/reproducible-builds.rst → docs/user/guides/reproducible-builds.rst b/docs/guides/reproducible-builds.rst → docs/user/guides/reproducible-builds.rst
diff --git a/docs/guides/technical-docs-seo-guide.rst → .../user/guides/technical-docs-seo-guide.rst b/docs/guides/technical-docs-seo-guide.rst → .../user/guides/technical-docs-seo-guide.rst
diff --git a/docs/guides/wipe-environment.rst → docs/user/guides/wipe-environment.rst b/docs/guides/wipe-environment.rst → docs/user/guides/wipe-environment.rst
diff --git a/docs/hosting.rst → docs/user/hosting.rst b/docs/hosting.rst → docs/user/hosting.rst
diff --git a/docs/img/edit_on_github.png → docs/user/img/edit_on_github.png b/docs/img/edit_on_github.png → docs/user/img/edit_on_github.png
diff --git a/docs/img/logo.png → docs/user/img/logo.png b/docs/img/logo.png → docs/user/img/logo.png
diff --git a/docs/img/translation_bar.png → docs/user/img/translation_bar.png b/docs/img/translation_bar.png → docs/user/img/translation_bar.png