Merge branch 'master' into use-latest-setuptools

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

@@ -39,8 +39,8 @@ RUN ln -s /usr/bin/python3 /usr/bin/python
 
 WORKDIR /tmp
 
-RUN curl -O https://raw.githubusercontent.com/readthedocs/readthedocs.org/master/requirements/pip.txt
-RUN curl -O https://raw.githubusercontent.com/readthedocs/readthedocs.org/master/requirements/docker.txt
+COPY requirements/pip.txt pip.txt
+COPY requirements/docker.txt docker.txt
 RUN pip3 install --no-cache-dir -r docker.txt
 
 # Install readthedocs-ext only if GITHUB_TOKEN is provided

common

@@ -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/Dockerfile

@@ -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
 

dockerfiles/nginx/proxito.conf

@@ -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/ad-customization.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/advertising-details.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/advertising/ethical-advertising.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/api/v3.rst

@@ -29,9 +29,10 @@ Advertising-free
 .. _readthedocs.org: https://readthedocs.org
 .. _readthedocs.com: https://readthedocs.com
 
-.. toctree:: 
+.. toctree::
    :caption: Additional commercial features
 
    organizations
+   single-sign-on
    sharing
    analytics

docs/changelog.rst

@@ -22,6 +22,11 @@ The best way to think about this relationship is:
 
 *Owners* will create *Teams* to assign permissions to all *Members*.
 
+.. warning::
+
+   Owners, Members and Teams behave differently if you are using
+   :ref:`SSO with VCS provider (GitHub, Bitbucket or GitLab) <commercial/single-sign-on:SSO with VCS provider (GitHub, Bitbucket or GitLab)>`
+
 Team Types
 ~~~~~~~~~~
 
@@ -44,4 +49,3 @@ Roadrunner would set up a *Team* called *Contractors*.
 That team would have *Read Only* access to the *Road Builder* project.
 Then he would add *Wile E. Coyote* to the team.
 This would give him access to just this one project inside the organization.
-

docs/commercial/index.rst

@@ -0,0 +1,138 @@
+Single Sign-On
+==============
+
+.. note::
+
+   This feature only exists on `Read the Docs for Business <https://readthedocs.com/>`__.
+
+
+Single Sign-On is supported on |com_brand| for Pro and Enterprise plans.
+:abbr:`SSO (Single Sign-On)` will allow you to grant permissions to your organization's projects in an easy way.
+
+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 (*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, Bitbucket, GitLab and Google are supported for now.
+   If you would like to apply for the Beta, please `contact us <mailto:[email protected]>`_.
+
+.. contents::
+   :local:
+   :depth: 2
+
+
+SSO with VCS provider (GitHub, Bitbucket or GitLab)
+---------------------------------------------------
+
+Using an Identity Provider that supports authentication and authorization allows you to manage
+"who have access to what projects on Read the Docs" directly from the provider itself.
+In case you want a user to have access to your documentation project under Read the Docs,
+that user just needs to be granted permissions in the VCS repository associated with it.
+
+Note the users created under Read the Docs must have their GitHub, Bitbucket or GitLab
+:doc:`account connected </connected-accounts>` in order to make SSO to work.
+
+.. note::
+
+   You can read more about `granting permissions on GitHub`_.
+
+   .. _granting permissions on GitHub: https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization
+
+
+Grant access to read the documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By granting **read** (or more) permissions to a user in the VCS repository
+you are giving access to read the documentation of the associated project on Read the Docs to that user.
+
+
+Grant access to administrate a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By granting **write** permission to a user in the VCS repository
+you are giving access to read the documentation *and* to be an administrator
+of the associated project on Read the Docs to that user.
+
+
+Grant access to import a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When SSO with VCS provider is enabled only owners of the Read the Docs organization can import projects.
+Adding users as owners of your organization will give them permissions to import projects.
+
+Note that to be able to import a project, that user must have **admin** permissions in the VCS repository associated.
+
+
+Revoke access to a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can add a user under an "Admin Team" to grant **admin** permissions to all the projects under that Team.
+This can be done under "your organization detail's page" > :guilabel:`Teams` > :guilabel:`Admins` > :guilabel:`Invite Member`.
+
+
+Grant access to users to import a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Making the user member of any "Admin Team" under your organization (as mentioned in the previous section),
+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/organizations.rst

@@ -110,6 +110,8 @@ def get_version():
 # Activate autosectionlabel plugin
 autosectionlabel_prefix_document = True
 
+numfig = True
+
 # sphinx-notfound-page
 # https://github.com/readthedocs/sphinx-notfound-page
 notfound_context = {
@@ -125,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',
@@ -133,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/commercial/single-sign-on.rst

@@ -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::