Merge branch 'master' into cross-reference-guide

Author: stsewd

.readthedocs.yml

@@ -15,3 +15,6 @@ search:
 
     # Internal documentation
     development/design/*: -5
+
+    # Useful content, but not something we want most users finding
+    custom_installs/*: -6

.travis.yml

@@ -10,7 +10,7 @@ addons:
 jobs:
   include:
     - python: 3.6
-      env: TOXENV=py36,codecov TOX_POSARGS='' ES_VERSION=6.2.4 ES_DOWNLOAD_URL=https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-${ES_VERSION}.tar.gz
+      env: TOXENV=py36,codecov TOX_POSARGS='' ES_VERSION=6.5.4 ES_DOWNLOAD_URL=https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-${ES_VERSION}.tar.gz
     - python: 3.6
       env: TOXENV=docs
     - python: 3.6

CHANGELOG.rst

@@ -64,6 +64,8 @@ server {
         add_header X-RTD-Redirect $rtd_redirect always;
         set $cache_tag $upstream_http_cache_tag;
         add_header Cache-Tag $cache_tag always;
+        set $referrer_policy $upstream_http_referrer_policy;
+        add_header Referrer-Policy $referrer_policy always;
     }
 
     # Serve 404 pages here

dockerfiles/nginx/proxito.conf

@@ -38,8 +38,8 @@ In Sphinx, this is typically done by
 adding a new template (under `templates_path`_)
 for inclusion in the `HTML sidebar`_ in your ``conf.py``.
 
-.. _HTML sidebar: http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars
-.. _templates_path: http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-templates_path
+.. _HTML sidebar: https://www.sphinx-doc.org/page/usage/configuration.html#confval-html_sidebars
+.. _templates_path: https://www.sphinx-doc.org/page/usage/configuration.html#confval-templates_path
 
 .. code-block:: python
 

docs/advertising/ad-customization.rst

@@ -71,8 +71,6 @@ Instead, we target based solely upon:
     targeting by state or by metro area (DMA specifically).
   * We geolocate a user's IP address to a country when a request is made.
 
-Read the Docs uses GeoLite2 data created by `MaxMind <http://maxmind.com>`_.
-
 
 Where ads are shown
 -------------------
@@ -97,6 +95,14 @@ For more details, see the :ref:`Do Not Track section <privacy-policy:Do Not Trac
 of our privacy policy.
 
 
+Ad serving infrastructure
+-------------------------
+
+Our `entire ad server <https://github.com/readthedocs/ethical-ad-server>`_ is open source,
+so you can inspect how we're doing things.
+We believe strongly in open source, and we practice what we preach.
+
+
 Analytics
 ---------
 

docs/advertising/advertising-details.rst

@@ -74,6 +74,9 @@ They should run before your content,
 they should take over the page,
 the bigger, weirder, or flashier the better.
 
+.. _fake ad clicks: https://en.wikipedia.org/wiki/Click_fraud
+.. _massive downsides: http://idlewords.com/talks/what_happens_next_will_amaze_you.htm
+
 We opt out
 ~~~~~~~~~~
 
@@ -91,8 +94,6 @@ The ads won't flash or move.
 We run the ads we want to have on our site,
 in a way that makes us feel good.
 
-.. _fake ad clicks: https://en.wikipedia.org/wiki/Click_fraud
-
 Additional details
 ------------------
 
@@ -105,6 +106,8 @@ Additional details
 * Eric Holscher, one of our co-founders
   `talks a bit more <https://www.ericholscher.com/blog/2016/aug/31/funding-oss-marketing-money/>`_
   about funding open source this way on his blog.
+* After proving our ad model as a way to fund open source and building our ad serving infrastructure,
+  we launched the `EthicalAds network <https://www.ethicalads.io>`_ to help other projects be sustainable.
 
 .. _advertising FAQ: https://readthedocs.org/sustainability/advertising/faq/
 
@@ -120,8 +123,6 @@ We hope that others will join us in this mission:
   vote with your dollars and support us in building the ad model we want to exist.
   `Get more information <https://readthedocs.org/sustainability/advertising/>`_ on what we offer.
 
-.. _massive downsides: http://idlewords.com/talks/what_happens_next_will_amaze_you.htm
-
 
 Community Ads
 -------------

docs/advertising/ethical-advertising.rst

@@ -1364,3 +1364,8 @@ Environment Variable delete
     :requestheader Authorization: token to authenticate.
 
     :statuscode 204: Environment variable deleted successfully
+
+Additional APIs
+---------------
+
+- :ref:`Server side search API <server-side-search:api>`.

docs/api/v3.rst

@@ -24,12 +24,13 @@ Code Notes
 - Updated Django from `1.6.11` to `1.8.3`.
 - Removed South and ported the South migrations to Django's migration framework.
 - Updated django-celery from `3.0.23` to `3.1.26` as django-celery 3.0.x does not support Django 1.8.
-- Updated Celery from `3.0.24` to `3.1.18` because we had to update django-celery. We need to test this extensively and might need to think about using the new Celery API directly and dropping django-celery. See release notes: http://docs.celeryproject.org/en/latest/whatsnew-3.1.html
+- Updated Celery from `3.0.24` to `3.1.18` because we had to update django-celery. We need to test this extensively and might need to think about using the new Celery API directly and dropping django-celery.
+  See release notes: https://docs.celeryproject.org/en/3.1/whatsnew-3.1.html
 - Updated tastypie from `0.11.1` to current master (commit `1e1aff3dd4dcd21669e9c68bd7681253b286b856`) as 0.11.x is not compatible with Django 1.8. No surprises expected but we should ask for a proper release, see release notes: https://github.com/django-tastypie/django-tastypie/blob/master/docs/release_notes/v0.12.0.rst
-- Updated django-oauth from `0.16.1` to `0.21.0`. No surprises expected, see release notes `in the docs <https://django-allauth.readthedocs.org/en/latest/changelog.html>`_ and `finer grained in the repo <https://github.com/pennersr/django-allauth/blob/9123223f167959e4e5c4074408db068f725559d1/ChangeLog#L1-169>`_
+- Updated django-oauth from `0.16.1` to `0.21.0`. No surprises expected, see release notes `in the docs <https://django-allauth.readthedocs.io/en/latest/release-notes.html>`_ and `finer grained in the repo <https://github.com/pennersr/django-allauth/blob/9123223f167959e4e5c4074408db068f725559d1/ChangeLog#L1-169>`_
 - Updated django-guardian from `1.2.0` to `1.3.0` to gain Django 1.8 support. No surprises expected, see release notes: https://github.com/lukaszb/django-guardian/blob/devel/CHANGES
 - Using `django-formtools` instead of removed `django.contrib.formtools` now. Based on the Django release notes, these modules are the same except of the package name.
-- Updated pytest-django from `2.6.2` to `2.8.0`. No tests required, but running the testsuite :smile: 
+- Updated pytest-django from `2.6.2` to `2.8.0`. No tests required, but running the testsuite :smile:
 - Updated psycopg2 from 2.4 to 2.4.6 as 2.4.5 is required by Django 1.8. No trouble expected as Django is the layer between us and psycopg2. Also it's only a minor version upgrade. Release notes: http://initd.org/psycopg/docs/news.html#what-s-new-in-psycopg-2-4-6
 - Added `django.setup()` to `conf.py` to load django properly for doc builds.
 - Added migrations for all apps with models in the `readthedocs/` directory

docs/changelog.rst

@@ -12,11 +12,11 @@ Single Sign-On is supported on |com_brand| for Pro and Enterprise plans.
 Currently, we support two different types of Single Sign-On:
 
 * Authentication *and* authorization are managed by the Identity Provider (e.g. GitHub, Bitbucket or GitLab)
-* Authentication is managed by the Identity Provider (e.g. a ``@company.com`` verified email address)
+* Authentication (*only*) is managed by the Identity Provider (e.g. an active GSuite/Google ``@company.com`` with a verified email address)
 
 .. note::
 
-   SSO is currently in **Beta** and only GitHub and Company Email are supported for now.
+   SSO is currently in **Beta** and only GitHub, Bitbucket, GitLab and Google are supported for now.
    If you would like to apply for the Beta, please `contact us <mailto:[email protected]>`_.
 
 .. contents::
@@ -66,11 +66,45 @@ Adding users as owners of your organization will give them permissions to import
 Note that to be able to import a project, that user must have **admin** permissions in the VCS repository associated.
 
 
-SSO with your company email address
------------------------------------
+Revoke access to a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Using your company's email address (e.g. ``[email protected]``) allows you to
-"grant **read** access to all the projects under your organization to users with a ``@company.com`` verified email address".
+If a user should not have access anymore to a project for any reason,
+a VCS repository's admin (e.g. user with Admin role on GitHub for that specific repository)
+can revoke access to the VCS repository and this will be automatically reflected in Read the Docs.
+
+The same process is followed in case you need to remove **admin** access,
+but still want that user to have access to read the documentation.
+Instead of revoking access completely, just need lower down permissions to **read** only.
+
+
+SSO with GSuite (Google email account)
+--------------------------------------
+
+Using your company's Google email address (e.g. ``[email protected]``) allows you to
+manage authentication for your organization's members.
+As this Identity Provider does not provide authorization over each repositories/projects per user,
+permissions are managed by the :ref:`internal Read the Docs's Teams <commercial/organizations:Team Types>` authorization system.
+
+By default, users that Sign Up with a Google account do not have any permissions over any project.
+However, you can define which Teams users matching your company's domain email address will auto-join when they Sign Up.
+Read the following sections to learn how to grant read and admin access.
+
+
+Grant access to read a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can add a user under a "Read Only Team" to grant **read** permissions to all the projects under that Team.
+This can be done under "your organization detail's page" > :guilabel:`Teams` > :guilabel:`Read Only` > :guilabel:`Invite Member`.
+
+To avoid this repetitive task for each employee of your company,
+the owner of the Read the Docs organization can mark one or many Teams for users matching the company's domain email
+to join these Teams automaically when they Sign Up.
+
+For example, you can create a "General Documentaion (Read Only)" team
+with the projects that all employees of your company should have access to
+and mark it as :guilabel:`Auto join users with an organization's email address to this team`.
+Then all users that Sign Up with their ``[email protected]`` email will automatically join this Team and have **read** access to those projects.
 
 
 Grant access to administer a project
@@ -88,3 +122,17 @@ they will be granted access to import a project.
 
 Note that to be able to import a project, that user must have **admin** permissions in the GitHub, Bitbucket or GitLab repository associated,
 and their social account connected with Read the Docs.
+
+
+Revoke user's access to a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To revoke access to a project for a particular user, you should remove that user from the Team that contains that Project.
+This can be done under "your organization detail's page" > :guilabel:`Teams` > :guilabel:`Read Only` and click :guilabel:`Remove` next to the user you want to revoke access.
+
+
+Revoke user's access to all the projects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By disabling the GSuite/Google account with email ``[email protected]``,
+you revoke access to all the projects that user had access and disable login on Read the Docs completely for that user.

docs/commercial/single-sign-on.rst

@@ -127,6 +127,7 @@ def get_version():
 linkcheck_ignore = [
     r'http://127\.0\.0\.1',
     r'http://localhost',
+    r'http://community\.dev\.readthedocs\.io',
     r'https://yourproject\.readthedocs\.io',
     r'https?://docs\.example\.com',
     r'https://foo\.readthedocs\.io/projects',
@@ -135,6 +136,8 @@ def get_version():
     r'https://github\.com/readthedocs/readthedocs\.org/pull',
     r'https://docs\.readthedocs\.io/\?rtd_search',
     r'https://readthedocs\.org/search',
+    # This page is under login
+    r'https://readthedocs\.org/accounts/gold',
 ]
 
 

docs/conf.py

@@ -18,7 +18,7 @@ The main advantages of using a configuration file over the web interface are:
 - Some settings are only available using a configuration file
 
 .. tip::
-   
+
    Using a configuration file is the recommended way of using Read the Docs.
 
 .. toctree::

docs/config-file/index.rst

@@ -19,7 +19,7 @@ Here is an example of what this file looks like:
 
    build:
      image: latest
-   
+
    python:
      version: 3.6
      setup_py_install: true
@@ -34,7 +34,7 @@ version
 * Default: 1
 
 .. code-block:: yaml
-   
+
    version: 1
 
 
@@ -49,7 +49,7 @@ The formats of your documentation you want to be built.
 Set as an empty list ``[]`` to build none of the formats.
 
 .. note:: We will always build an HTML & JSON version of your documentation.
-		  These are used for web serving & search indexing, respectively.
+          These are used for web serving & search indexing, respectively.
 
 .. code-block:: yaml
 
@@ -146,7 +146,7 @@ This is the version of Python to use when building your documentation.
 If you specify only the major version of Python,
 the highest supported minor version will be selected.
 
-.. warning:: 
+.. warning::
 
     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
@@ -186,8 +186,8 @@ When true, install your project into the Virtualenv with
 
 .. code-block:: yaml
 
-	python:
-	   setup_py_install: true
+        python:
+           setup_py_install: true
 
 
 python.pip_install
@@ -204,37 +204,6 @@ documentation.
     python:
        pip_install: true
 
-
-.. TODO not yet implemented. We should move these to another doc.
-.. ==============================================================
-.. 
-.. type
-.. ~~~~
-.. 
-.. * Default: ``sphinx``
-.. * Options: ``sphinx``, ``mkdocs``
-.. 
-.. The ``type`` block allows you to configure the build tool used for building
-.. your documentation.
-.. 
-.. .. code-block:: yaml
-.. 
-..     type: sphinx
-.. 
-.. conf_file
-.. ~~~~~~~~~
-.. 
-.. * Default: `None`
-.. * Type: Path (specified from the root of the project)
-.. 
-.. The path to a specific Sphinx ``conf.py`` file. If none is found, we will
-.. choose one.
-.. 
-.. .. code-block:: yaml
-.. 
-..     conf_file: project2/docs/conf.py
-
-
 python.extra_requirements
 `````````````````````````
 
@@ -284,6 +253,6 @@ Behind the scene the following Pip command will be run:
     pip install .[tests,docs]
 
 
-.. _environment file: http://conda.pydata.org/docs/using/envs.html#share-an-environment
+.. _environment file: https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file
 .. _extra requirements: https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies
 .. _package default dependencies: https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-dependencies

docs/config-file/v1.rst

@@ -5,6 +5,7 @@ Read the Docs supports configuring your documentation builds with a YAML file.
 The :doc:`configuration file <index>` must be in the root directory of your project.
 We recommend the filename ``.readthedocs.yml``.
 
+All options are applied to the version containing this file.
 Below is an example YAML file which shows the most common configuration options:
 
 .. code:: yaml
@@ -340,7 +341,8 @@ Read the Docs will try to find a ``conf.py`` file in your project.
 sphinx.fail_on_warning
 ``````````````````````
 
-`Turn warnings into errors <http://www.sphinx-doc.org/en/master/man/sphinx-build.html#id6>`__.
+Turn warnings into errors
+(:option:`-W <sphinx:sphinx-build.-W>` and :option:`--keep-going <sphinx:sphinx-build.--keep-going>` options).
 This means the build fails if there is a warning and exits with exit status 1.
 
 :Type: ``bool``

docs/config-file/v2.rst

@@ -200,9 +200,9 @@ Yes. One criticism of Sphinx is that its annotated docstrings are too
 dense and difficult for humans to read. In response, many projects
 have adopted customized docstring styles that are simultaneously
 informative and legible. The
-`NumPy <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_
+`NumPy <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`__
 and
-`Google <https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments>`_
+`Google <https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings>`__
 styles are two popular docstring formats.  Fortunately, the default
 Read The Docs theme handles both formats just fine, provided
 your ``conf.py`` specifies an appropriate Sphinx extension that
@@ -251,6 +251,23 @@ using a Read the Docs :doc:`config-file/index`.
 .. _pip requirements file: https://pip.pypa.io/en/stable/user_guide.html#requirements-files
 
 
+I need to install a package in a environment with pinned versions
+-----------------------------------------------------------------
+
+To ensure proper installation of a python package, the ``pip`` :ref:`install method <config-file/v2:python.install>` will automatically upgrade every dependency to its most recent version in case they aren't pinned by the package definition.
+If instead you'd like to pin your dependencies outside the package, you can add this line to your requirements or environment file (if you are using Conda).
+
+In your ``requirements.txt`` file::
+
+    # path to the directory containing setup.py relative to the project root
+    -e .
+
+In your Conda environment file (``environment.yml``)::
+
+    # path to the directory containing setup.py relative to the environment file
+    -e ..
+
+
 How can I avoid search results having a deprecated version of my docs?
 ----------------------------------------------------------------------