Treat docs warnings as errors

docs/.rstcheck.cfg

@@ -1,4 +1,6 @@
 [rstcheck]
 ignore_directives=automodule,http:get,tabs,tab,prompt,http:patch,http:post
 ignore_roles=djangosetting,setting,featureflags,buildpyversions
-ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced)
+# This error needs to be ignored for now
+# See: https://github.com/myint/rstcheck/issues/19
+ignore_messages=(Hyperlink target ".*" is not referenced)

docs/Makefile

@@ -2,11 +2,14 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W --keep-going
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
 
+# Do not use local Django settings during the docs build
+export DJANGO_SETTINGS_SKIP_LOCAL = True
+
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
 $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)

docs/advertising/ad-customization.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Customizing Advertising
 =======================
 

docs/advertising/advertising-details.rst

@@ -97,16 +97,15 @@ Currently we show ads on:
 * Sphinx theme provided by Read the Docs
 * MkDocs theme provided by Read the Docs (beginning in May 2018)
 * Alabaster Sphinx theme
-* [Pylons Sphinx Themes](https://github.com/Pylons/pylons-sphinx-themes), including pyramid, pylons, and pylonsfw.
+* `Pylons Sphinx Themes <https://github.com/Pylons/pylons-sphinx-themes>`_,
+  including pyramid, pylons, and pylonsfw.
 
 This list will expand as we strive to put advertising on a
 larger percentage of the documentation served by us.
 However, we always give advance notice in our issue tracker
 and via email about showing ads where none were shown before.
 
 
-.. _advertising-details-do-not-track:
-
 Do Not Track Policy
 -------------------
 
@@ -115,8 +114,6 @@ For more details, see the :ref:`Do Not Track section <privacy-policy:Do Not Trac
 of our privacy policy.
 
 
-.. _advertising-analytics:
-
 Analytics
 ---------
 

docs/api/v1.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 API v1 (removed)
 ================
 

docs/api/v3.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 API v3
 ======
 

docs/commercial/custom_domains.rst

@@ -8,8 +8,9 @@ Once a project is imported under Read the Docs,
 by default it's hosted under a subdomain on one of our domains.
 If you need a custom domain, continue on custom domain setup.
 
-Custom domains
---------------
+
+Serving documentation with a custom domain
+------------------------------------------
 
 Projects can also be hosted under a custom domain.
 If you'd prefer to use your own domain name instead of our default hosting domain,

docs/config-file/v1.rst

@@ -37,7 +37,6 @@ version
 
    version: 1
 
-.. _yaml__formats:
 
 formats
 ~~~~~~~
@@ -64,7 +63,6 @@ Set as an empty list ``[]`` to build none of the formats.
         - epub
         - pdf
 
-.. _yaml__requirements_file:
 
 requirements_file
 ~~~~~~~~~~~~~~~~~
@@ -78,7 +76,6 @@ The path to your pip requirements file.
 
    requirements_file: requirements/docs.txt
 
-.. _yaml__conda:
 
 conda
 ~~~~~
@@ -100,14 +97,12 @@ The file option specified the Conda `environment file`_ to use.
 
 .. note:: Conda is only supported via the YAML file.
 
-.. _yaml__build:
 
 build
 ~~~~~
 
 The ``build`` block configures specific aspects of the documentation build.
 
-.. _yaml__build__image:
 
 build.image
 ```````````
@@ -133,15 +128,13 @@ as defined here:
     python:
         version: 3.6
 
-.. _yaml__python:
 
 python
 ~~~~~~
 
 The ``python`` block allows you to configure aspects of the Python executable
 used for building documentation.
 
-.. _yaml__python__version:
 
 python.version
 ``````````````
@@ -157,8 +150,8 @@ the highest supported minor version will be selected.
 
     The supported Python versions depends on the version of the build image your
     project is using. The default build image that is used to build
-    documentation contains support for Python ``2.7`` and ``3.7``.  See the
-    :ref:`yaml__build__image` for more information on supported Python versions.
+    documentation contains support for Python ``2.7`` and ``3.7``.
+    See :ref:`config-file/v1:build.image` for more information on supported Python versions.
 
 .. code-block:: yaml
 
@@ -181,7 +174,6 @@ See :ref:`builds:The build environment` for more details.
     python:
        use_system_site_packages: true
 
-.. _yaml__python__setup_py_install:
 
 python.setup_py_install
 ```````````````````````
@@ -197,7 +189,6 @@ When true, install your project into the Virtualenv with
 	python:
 	   setup_py_install: true
 
-.. _yaml__python__pip_install:
 
 python.pip_install
 ``````````````````
@@ -243,7 +234,6 @@ documentation.
 .. 
 ..     conf_file: project2/docs/conf.py
 
-.. _yaml__python__extra_requirements:
 
 python.extra_requirements
 `````````````````````````
@@ -294,7 +284,6 @@ Behind the scene the following Pip command will be run:
     pip install .[tests,docs]
 
 
-.. _issue: https://github.com/rtfd/readthedocs.org/issues
 .. _environment file: http://conda.pydata.org/docs/using/envs.html#share-an-environment
 .. _extra requirements: http://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies
 .. _package default dependencies: http://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-dependencies

docs/contribute.rst

@@ -25,7 +25,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 <install>`. After that is done we
+:doc:`Installation Guide <development/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.
@@ -103,7 +103,35 @@ 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:`docs`.
+For full details, including how to build it, see :doc:`/development/docs`.
+
+
+Developer documentation
+-----------------------
+
+These are guides and helpful documentation to running your own local version of Read the Docs
+for development or taking the open source Read the Docs codebase
+for your own :doc:`custom installation <custom_installs/index>`.
+
+.. toctree::
+   :maxdepth: 1
+
+   development/install
+   development/search
+   development/architecture
+   development/tests
+   development/docs
+   development/design/index
+   development/standards
+   development/buildenvironments
+   development/symlinks
+   development/settings
+   development/i18n
+   development/issue-labels
+   development/design
+   RTD Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>
+
+
 
 Triaging tickets
 ----------------
@@ -244,7 +272,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:`issue-labels`.
+:doc:`/development/issue-labels`.
 
 Helpful links for triaging
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/custom_installs/customization.rst

@@ -1,7 +1,7 @@
 Customizing your install
 ========================
 
-Read the Docs has a lot of :doc:`/settings` that help customize your install.
+Read the Docs has a lot of :doc:`/development/settings` that help customize your install.
 This document will outline some of the more useful ways that these can be combined.
 
 Have a local settings file

docs/custom_installs/local_rtd_vm.rst

@@ -47,8 +47,8 @@ To host your documentation on a local RTD installation, set it up in your VM:
     cd readthedocs.org
     sudo pip install -r requirements.txt
 
-Possible Error and Resolution
-`````````````````````````````
+Possible errors with a local RTD setup
+``````````````````````````````````````
 
 **Error**: ``error: command 'gcc' failed with exit status 1``
 
@@ -116,8 +116,8 @@ Go to the dashboard at  ``http://[VM IP ADDRESS]:8000/dashboard`` and follow the
 
 This generates the HTML documentation site using the default Sphinx theme. Verify the output in your local documentation folder under ``../build/html``
 
-Possible Error and Resolution
-`````````````````````````````
+Possible errors administering a RTD server
+``````````````````````````````````````````
 
 **Error**: Couldn't access Git Corp from VM.
 
@@ -136,9 +136,9 @@ Possible Error and Resolution
 3. Now, SSH to the VM.
 4. Open the ``id_rsa`` file in the VM:
 
-.. prompt:: bash $
+    .. prompt:: bash $
 
-    vim /home/<username>/.ssh/id_rsa
+        vim /home/<username>/.ssh/id_rsa
 
 5. Paste the RSA key copied from your machine and save file (``Esc``. ``:wq!``).
 

docs/design.rst → docs/development/design.rst

@@ -33,7 +33,7 @@ documentation using the default RTD style.
 Contributing
 ------------
 
-Contributions should follow the :doc:`contribute` guidelines where applicable -- ideally you'll
+Contributions should follow the :doc:`../contribute` guidelines where applicable -- ideally you'll
 create a pull request against the `Read the Docs GitHub project`_ from your forked repo and include
 a brief description of what you added / removed / changed, as well as an attached image (you can just
 take a screenshot and drop it into the PR creation form) of the effects of your changes.

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

docs/install.rst → docs/development/install.rst

@@ -178,9 +178,9 @@ Further steps
 
 By now you can trigger builds on your local environment,
 to encapsulate the build process inside a Docker container,
-see :doc:`development/buildenvironments`.
+see :doc:`buildenvironments`.
 
 For building this documentation,
 see :doc:`docs`.
 
-And for setting up for the front end development, see :doc:`development/standards`.
+And for setting up for the front end development, see :doc:`standards`.

docs/development/search.rst

@@ -78,10 +78,11 @@ We also index project information in our search index so that the user can searc
 from the main site. We listen to the `post_create` and `post_delete` signals of
 `Project` model and index/delete into Elasticsearch accordingly.
 
+
 Elasticsearch Document
 ~~~~~~~~~~~~~~~~~~~~~~
 
-`elasticsearch-dsl`_ provides model-like wrapper for the `Elasticsearch document`_.
+`elasticsearch-dsl`_ provides a model-like wrapper for `the Elasticsearch document`_.
 As per requirements of `django-elasticsearch-dsl`_, it is stored in the
 `readthedocs/search/documents.py` file.
 
@@ -103,7 +104,7 @@ As per requirements of `django-elasticsearch-dsl`_, it is stored in the
 .. _Elasticsearch: https://www.elastic.co/products/elasticsearch
 .. _Elasticsearch 6.3: https://www.elastic.co/guide/en/elasticsearch/reference/6.3/index.html
 .. _GitHub Repository: https://github.com/rtfd/readthedocs.org/tree/master/readthedocs/search
-.. _Elasticsearch document: https://www.elastic.co/guide/en/elasticsearch/guide/current/document.html
+.. _the Elasticsearch document: https://www.elastic.co/guide/en/elasticsearch/guide/current/document.html
 .. _django-elasticsearch-dsl: https://github.com/sabricot/django-elasticsearch-dsl
 .. _elasticsearch-dsl: http://elasticsearch-dsl.readthedocs.io/en/latest/
 .. _signals: https://docs.djangoproject.com/en/2.1/topics/signals/

docs/tests.rst → docs/development/tests.rst

@@ -31,17 +31,17 @@ To target a specific environment::
     tox -e py36
 
 The ``tox`` configuration has the following environments configured. You can
-target a single environment to limit the test suite::
+target a single environment to limit the test suite:
 
-    py36
-        Run our test suite using Python 3.6
+py36
+    Run our test suite using Python 3.6
 
-    lint
-        Run code linting using `Prospector`_. This currently runs `pylint`_,
-        `pyflakes`_, `pep8`_ and other linting tools.
+lint
+    Run code linting using `Prospector`_. This currently runs `pylint`_,
+    `pyflakes`_, `pep8`_ and other linting tools.
 
-    docs
-        Test documentation compilation with Sphinx.
+docs
+    Test documentation compilation with Sphinx.
 
 .. _`Tox`: http://tox.readthedocs.io/en/latest/index.html
 .. _`Prospector`: http://prospector.readthedocs.io/en/master/