Merge branch 'master' of github.com:rtfd/readthedocs.org into gsoc-19-pr-builder

Author: ericholscher

CHANGELOG.rst

@@ -1,3 +1,35 @@
+Version 3.5.3
+-------------
+
+:Date: June 19, 2019
+
+* `@davidfischer <http://github.com/davidfischer>`__: Treat docs warnings as errors (`#5825 <https://github.com/rtfd/readthedocs.org/pull/5825>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Fix some unclear verbiage (`#5820 <https://github.com/rtfd/readthedocs.org/pull/5820>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Rework documentation index page (`#5819 <https://github.com/rtfd/readthedocs.org/pull/5819>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Upgrade intersphinx to Django 1.11 (`#5818 <https://github.com/rtfd/readthedocs.org/pull/5818>`__)
+* `@pyup-bot <http://github.com/pyup-bot>`__: pyup:  Scheduled weekly dependency update for week 24 (`#5817 <https://github.com/rtfd/readthedocs.org/pull/5817>`__)
+* `@humitos <http://github.com/humitos>`__: Disable changing domain when editing the object (`#5816 <https://github.com/rtfd/readthedocs.org/pull/5816>`__)
+* `@saadmk11 <http://github.com/saadmk11>`__: Update docs with sitemap sort order change (`#5815 <https://github.com/rtfd/readthedocs.org/pull/5815>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Optimize requests to APIv3 (`#5803 <https://github.com/rtfd/readthedocs.org/pull/5803>`__)
+* `@ericholscher <http://github.com/ericholscher>`__: Show build length in the admin (`#5802 <https://github.com/rtfd/readthedocs.org/pull/5802>`__)
+* `@stsewd <http://github.com/stsewd>`__: Move search functions (`#5801 <https://github.com/rtfd/readthedocs.org/pull/5801>`__)
+* `@ericholscher <http://github.com/ericholscher>`__: A few small improvements to help with search admin stuff (`#5800 <https://github.com/rtfd/readthedocs.org/pull/5800>`__)
+* `@stsewd <http://github.com/stsewd>`__: Simplify es indexing (`#5798 <https://github.com/rtfd/readthedocs.org/pull/5798>`__)
+* `@humitos <http://github.com/humitos>`__: Use a real SessionBase object on FooterNoSessionMiddleware (`#5797 <https://github.com/rtfd/readthedocs.org/pull/5797>`__)
+* `@stsewd <http://github.com/stsewd>`__: Add logging in magic methods (`#5795 <https://github.com/rtfd/readthedocs.org/pull/5795>`__)
+* `@stsewd <http://github.com/stsewd>`__: Fix unbound var in search view (`#5794 <https://github.com/rtfd/readthedocs.org/pull/5794>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Mention security issue in the changelog (`#5790 <https://github.com/rtfd/readthedocs.org/pull/5790>`__)
+* `@stsewd <http://github.com/stsewd>`__: Index path with original path name (`#5785 <https://github.com/rtfd/readthedocs.org/pull/5785>`__)
+* `@stsewd <http://github.com/stsewd>`__: Use querysets from the class not from an instance (`#5783 <https://github.com/rtfd/readthedocs.org/pull/5783>`__)
+* `@saadmk11 <http://github.com/saadmk11>`__: Add Build managers and Update Build Querysets. (`#5779 <https://github.com/rtfd/readthedocs.org/pull/5779>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Project advertising page/form update (`#5777 <https://github.com/rtfd/readthedocs.org/pull/5777>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Update docs around opt-out of ads (`#5776 <https://github.com/rtfd/readthedocs.org/pull/5776>`__)
+* `@saadmk11 <http://github.com/saadmk11>`__: Sitemap sort order priorities updated (`#5724 <https://github.com/rtfd/readthedocs.org/pull/5724>`__)
+* `@dojutsu-user <http://github.com/dojutsu-user>`__: [Design Doc] In Doc Search UI (`#5707 <https://github.com/rtfd/readthedocs.org/pull/5707>`__)
+* `@saadmk11 <http://github.com/saadmk11>`__: Pull Request Builder Design Doc (`#5705 <https://github.com/rtfd/readthedocs.org/pull/5705>`__)
+* `@humitos <http://github.com/humitos>`__: Support single version subprojects URLs to serve from Django (`#5690 <https://github.com/rtfd/readthedocs.org/pull/5690>`__)
+* `@agjohnson <http://github.com/agjohnson>`__: Add a contrib Dockerfile for local build image on Linux (`#4608 <https://github.com/rtfd/readthedocs.org/pull/4608>`__)
+
 Version 3.5.2
 -------------
 

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/advertising/ethical-advertising.rst

@@ -155,26 +155,32 @@ Opting Out
 
 We have added multiple ways to opt out of the advertising on Read the Docs.
 
-Users can go ad-free
-by becoming a `Gold Member <https://readthedocs.org/accounts/gold/>`_
-or a `Supporter <https://readthedocs.org/sustainability/#donations>`_.
+1. You can go completely ad-free
+   by becoming a `Gold Member <https://readthedocs.org/accounts/gold/>`_
+   or a `Supporter <https://readthedocs.org/sustainability/#donations>`_.
 
-Users can opt out of seeing paid advertisements on documentation pages:
+2. You can opt out of seeing paid advertisements on documentation pages:
 
-* Go to the drop down user menu in the top right of the Read the Docs dashboard and clicking :guilabel:`Settings` (https://readthedocs.org/accounts/edit/).
-* On the :guilabel:`Advertising` tab, you can deselect **See paid advertising**.
+   * Go to the drop down user menu in the top right of the Read the Docs dashboard and clicking :guilabel:`Settings` (https://readthedocs.org/accounts/edit/).
+   * On the :guilabel:`Advertising` tab, you can deselect **See paid advertising**.
 
-Project owners can also opt out of paid advertisements for their projects.
-You can change these options:
+   You will still see :ref:`community ads <advertising/ethical-advertising:Community Ads>`
+   for open source projects and conferences.
 
-* Go to your **project** page (`/projects/<slug>/`)
-* Go to :guilabel:`Admin` > :guilabel:`Advertising`
-* Change your advertising settings
+3. Project owners can also opt out of paid advertisements for their projects.
+   You can change these options:
 
-Project opt out options include:
+   * Go to your **project** page (`/projects/<slug>/`)
+   * Go to :guilabel:`Admin` > :guilabel:`Advertising`
+   * Change your advertising settings
 
-* Supporting us `financially <https://readthedocs.org/accounts/gold/subscription/>`_ by becoming a Gold Member.
-  This will disable all ads from showing on your project's documentation.
-* Supporting us with `your time <http://docs.readthedocs.org/en/latest/contribute.html?>`_ by contributing to the project.
-* Moving to our `paid product <https://readthedocs.com/pricing/?>`_ over at readthedocs.com.
-* Opting out without doing any of the above. This will make us a little sad, but we understand not everyone has the means to contribute back.
+4. If you are part of a company that uses Read the Docs to host documentation for a commercial product,
+   we offer `paid plans`_ on readthedocs.com that offer a completely ad-free experience, additional build resources,
+   and features like CDN support and private documentation.
+
+5. If you would like to completely remove advertising from your open source project,
+   but our commercial plans don't seem like the right fit,
+   please `get in touch`_ to discuss alternatives to advertising.
+
+.. _paid plans: https://readthedocs.com/pricing/
+.. _get in touch: mailto:[email protected]?subject=Alternatives+to+advertising

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/architecture.rst renamed to docs/development/architecture.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.rst renamed to docs/development/design.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