Treat warnings as errors in doc building

davidfischer · davidfischer · commit 19ec28adad47 · 2019-06-18T16:36:01.000-07:00
diff --git a/docs/Makefile b/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/)
diff --git a/docs/advertising/ad-customization.rst b/docs/advertising/ad-customization.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Customizing Advertising
 =======================
 
diff --git a/docs/api/v1.rst b/docs/api/v1.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 API v1 (removed)
 ================
 
diff --git a/docs/api/v3.rst b/docs/api/v3.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 API v3
 ======
 
diff --git a/docs/commercial/custom_domains.rst b/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,
diff --git a/docs/custom_installs/local_rtd_vm.rst b/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.
 
diff --git a/docs/guides/manage-translations.rst b/docs/guides/manage-translations.rst
@@ -38,8 +38,13 @@ To generate these ``.pot`` files it's needed to run this command from your ``doc
 
 .. tip::
 
-   We recommend configuring Sphinx to use :ref:`gettext_uuid <sphinx:gettext_uuid>` as ``True``
-   and also :ref:`gettext_compact <sphinx:gettext_compact>` as ``False`` to generate ``.pot`` files.
+   We recommend configuring Sphinx to use gettext_uuid_ as ``True``
+   and also gettext_compact_ as ``False`` to generate ``.pot`` files.
+
+   .. Unfortunately these are custom types and can't yet be used with intersphinx
+   .. https://github.com/sphinx-doc/sphinx/issues/5562
+   .. _gettext_uuid: https://www.sphinx-doc.org/en/latest/usage/configuration.html#confval-gettext_uuid
+   .. _gettext_compact: https://www.sphinx-doc.org/en/latest/usage/configuration.html#confval-gettext_compact
 
 
 This command will leave the generated files under ``_build/gettext``.
diff --git a/docs/privacy-policy.rst b/docs/privacy-policy.rst
@@ -92,8 +92,8 @@ User Personal Information does not include aggregated, non-personally identifyin
 We may use aggregated, non-personally identifying information to operate, improve,
 and optimize our website and service.
 
-Why do we collect this?
-+++++++++++++++++++++++
+Why do we collect this information?
++++++++++++++++++++++++++++++++++++
 
 - We need your User Personal Information to create your account, and to provide the services you request.
 - We use your User Personal Information, specifically your user name, to identify you on Read the Docs.
diff --git a/docs/team.rst b/docs/team.rst
@@ -29,8 +29,8 @@ This might include tasks like:
 * Asking for a project name to be released
 * Troubleshooting build errors
 
-Members
-~~~~~~~
+Support team members
+~~~~~~~~~~~~~~~~~~~~
 
 * `Eric Holscher <https://github.com/ericholscher>`__ (Pacific Time)
 * `Anthony Johnson <https://github.com/agjohnson>`__ (Mountain Time)
@@ -39,8 +39,8 @@ Members
 
 **Please don't email us personally for support on Read the Docs.** You can email support@readthedocs.org for any issues you may have. 
 
-Joining
-~~~~~~~
+Joining the support team
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 The best place to start would be to start addressing some of the issues in our issue tracker.
 We have our support policies quite well documented in our :doc:`/contribute`.
@@ -59,8 +59,8 @@ As part of operating the site,
 we maintain a 24/7 on-call rotation.
 This means that folks have to be available and have their phone in service.
 
-Members
-~~~~~~~
+Ops team members
+~~~~~~~~~~~~~~~~
 
 * `Eric Holscher <https://github.com/ericholscher>`_ (Pacific Time)
 * `Anthony Johnson <https://github.com/agjohnson>`_ (Mountain Time)
@@ -69,8 +69,8 @@ Members
 
 Feel free to ask any of us if you have questions or want to join!
 
-Joining
-~~~~~~~
+Joining the ops team
+~~~~~~~~~~~~~~~~~~~~
 
 We are always looking for more people to share the on-call responsibility.
 If you are on-call for your job already,
@@ -103,8 +103,8 @@ Development Team
 Also known as the "Core Team" in other projects.
 These folks have the ability to commit code to the project.
 
-Members
-~~~~~~~
+Dev team members
+~~~~~~~~~~~~~~~~
 
 * `Eric Holscher <https://github.com/ericholscher>`_
 * `Anthony Johnson <https://github.com/agjohnson>`_
@@ -115,8 +115,8 @@ Members
 
 Feel free to ask any of us if you have questions or want to join!
 
-Joining
-~~~~~~~
+Joining the dev team
+~~~~~~~~~~~~~~~~~~~~
 
 We try to be pretty flexible with who we allow on the development team.
 The best path is to send a few pull requests,
diff --git a/tox.ini b/tox.ini
@@ -25,7 +25,7 @@ commands =
 description = build readthedocs documentation
 changedir = {toxinidir}/docs
 commands =
-    sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
+    sphinx-build -W --keep-going -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
 
 [testenv:migrations]
 description = check for missing migrations

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`Customizing Advertising`
`2`	`4`	`=======================`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`API v1 (removed)`
`2`	`4`	`================`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+:orphan:`
	`2`	`+`
`1`	`3`	`API v3`
`2`	`4`	`======`
`3`	`5`