Merge remote-tracking branch 'origin/master' into humitos/lock/appropiate-log

Author: ericholscher

.coveragerc

@@ -17,3 +17,4 @@ exclude_lines =
     pragma: no cover
     raise NotImplementedError
     if __name__ == .__main__.:
+    if getattr(settings, 'DEBUG'):

.travis.yml

@@ -16,6 +16,8 @@ matrix:
       script: tox
     - python: 3.6
       env: TOXENV=eslint
+    - python: 3.6
+      env: TOXENV=migrations
 cache:
   directories:
     - ~/.cache/pip

CHANGELOG.rst

@@ -1,3 +1,26 @@
+Version 2.8.0
+-------------
+
+:Date: October 30, 2018
+
+Major change is an upgrade to Django 1.11. 
+
+* `@humitos <http://github.com/humitos>`__: Cleanup old code (remove old_div) (`#4817 <https://github.com/rtfd/readthedocs.org/pull/4817>`__)
+* `@humitos <http://github.com/humitos>`__: Remove unnecessary migration (`#4806 <https://github.com/rtfd/readthedocs.org/pull/4806>`__)
+* `@humitos <http://github.com/humitos>`__: Feature flag to make `readthedocs` theme default on MkDocs docs (`#4802 <https://github.com/rtfd/readthedocs.org/pull/4802>`__)
+* `@stsewd <http://github.com/stsewd>`__: Add codecov badge (`#4799 <https://github.com/rtfd/readthedocs.org/pull/4799>`__)
+* `@humitos <http://github.com/humitos>`__: Pin missing dependency for the MkDocs guide compatibility (`#4798 <https://github.com/rtfd/readthedocs.org/pull/4798>`__)
+* `@ericholscher <http://github.com/ericholscher>`__: Release 2.7.2 (`#4796 <https://github.com/rtfd/readthedocs.org/pull/4796>`__)
+* `@humitos <http://github.com/humitos>`__: Do not log as error a webhook with an invalid branch name (`#4779 <https://github.com/rtfd/readthedocs.org/pull/4779>`__)
+* `@ericholscher <http://github.com/ericholscher>`__: Run travis on release branches (`#4763 <https://github.com/rtfd/readthedocs.org/pull/4763>`__)
+* `@ericholscher <http://github.com/ericholscher>`__: Remove Eric & Anthony from ADMINS & MANAGERS settings (`#4762 <https://github.com/rtfd/readthedocs.org/pull/4762>`__)
+* `@stsewd <http://github.com/stsewd>`__: Don't use RequestsContext (`#4759 <https://github.com/rtfd/readthedocs.org/pull/4759>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Django 1.11 upgrade (`#4750 <https://github.com/rtfd/readthedocs.org/pull/4750>`__)
+* `@stsewd <http://github.com/stsewd>`__: Dropdown to select Advanced Settings (`#4710 <https://github.com/rtfd/readthedocs.org/pull/4710>`__)
+* `@stsewd <http://github.com/stsewd>`__: Remove hardcoded constant from config module (`#4704 <https://github.com/rtfd/readthedocs.org/pull/4704>`__)
+* `@stsewd <http://github.com/stsewd>`__: Update tastypie (`#4325 <https://github.com/rtfd/readthedocs.org/pull/4325>`__)
+* `@stsewd <http://github.com/stsewd>`__: Update to Django 1.10 (`#4319 <https://github.com/rtfd/readthedocs.org/pull/4319>`__)
+
 Version 2.7.2
 -------------
 

contrib/add-project.py

@@ -0,0 +1,168 @@
+"""
+Script to add a Git project as cloned from a Github repository
+to ReadTheDocs. Invoke from the checkout.
+"""
+
+__requires__ = ['requests-toolbelt', 'autocommand', 'keyring']
+
+
+import os
+import getpass
+import re
+import urllib.parse
+import subprocess
+import pathlib
+
+import autocommand
+import keyring
+from requests_toolbelt import sessions
+
+
+rtd = sessions.BaseUrlSession(
+    os.environ.get('RTD_URL', 'https://readthedocs.org/api/v2/'))
+github = sessions.BaseUrlSession('https://api.github.com/')
+github.headers.update(Accept='application/vnd.github.v3+json')
+
+
+class User:
+    """
+    A User (with a password) in RTD.
+
+    Resolves username using ``getpass.getuser()``. Override with
+    RTD_USERNAME environment variable.
+
+    Resolves password using keyring. Install keyring and run
+    ``keyring set https://readthedocs.org/ $USER`` to set the pw.
+    Override with RTD_PASSWORD environment variable.
+    """
+    def __init__(self):
+        self.name = os.environ.get('RTD_USERNAME') or getpass.getuser()
+        system = rtd.create_url('/')
+        self.password = (
+            os.environ.get('RTD_PASSWORD')
+            or keyring.get_password(system, self.name)
+        )
+
+    @property
+    def id(self):
+        resp = rtd.get('../v1/user/', params=dict(username=self.name))
+        resp.raise_for_status()
+        ob, = resp.json()['objects']
+        return ob['id']
+
+    @property
+    def tuple(self):
+        return self.name, self.password
+
+
+class Sluggable(str):
+    """
+    A name for use in RTD with a 'slug' version.
+    """
+    @property
+    def slug(self):
+        return self.replace('.', '')
+
+
+class Repo:
+    """
+    A Git repo
+    """
+
+    def __init__(self, root):
+        self.root = root
+        cmd = ['git', '-C', root, 'remote', 'get-url', 'origin']
+        proc = subprocess.run(
+            cmd, check=True, text=True, stdout=subprocess.PIPE)
+        self.url = proc.stdout.strip()
+
+    @property
+    def name(self):
+        return Sluggable(pathlib.Path(self.url).stem)
+
+
+def create_project(repo):
+    """
+    Create the project from a Repo
+    """
+    user = User()
+    payload = dict(
+        repo=repo.url,
+        slug=repo.name.slug,
+        name=repo.name,
+        users=[user.id],
+    )
+    resp = rtd.post('project/', json=payload, auth=user.tuple)
+    resp.raise_for_status()
+
+
+def configure_github(name, url):
+    """
+    Given a project name and webhook URL, configure the webhook
+    in GitHub.
+
+    Resolves username from ``getpass.getuser()``. Override with
+    ``GITHUB_USERNAME``.
+
+    Resolves access token from keyring for username and system
+    'github.com'. Override with ``GITHUB_TOKEN`` environment
+    variable.
+    """
+    user = os.environ.get('GITHUB_USERNAME') or getpass.getuser()
+    token = (
+        keyring.get_password('github.com', user)
+        or os.environ['GITHUB_TOKEN']
+    )
+    headers = dict(Authorization=f'token {token}')
+    path = f'/repos/{user}/{name}/hooks'
+    params = dict(
+        name='web',
+        config=dict(
+            url=url,
+            content_type='json',
+        ),
+    )
+    github.post(path, json=params, headers=headers)
+
+
+def configure_webhook(name):
+    """
+    Identify the webhook URL for a RTD project named name.
+    """
+    login_path = '/accounts/login/'
+    resp = rtd.get(login_path)
+    token = rtd.cookies.get('csrftoken') or rtd.cookies['csrf']
+    user = User()
+    params = dict(
+        login=user.name,
+        password=user.password,
+        csrfmiddlewaretoken=token,
+        next='/',
+    )
+    headers = dict(Referer=rtd.create_url(login_path))
+    resp = rtd.post(login_path, data=params, headers=headers)
+    token = rtd.cookies.get('csrftoken') or rtd.cookies['csrf']
+    params = dict(
+        integration_type='github_webhook',
+        csrfmiddlewaretoken=token,
+        next='/',
+    )
+    create_path = f'/dashboard/{name.slug}/integrations/create/'
+    headers = dict(
+        Referer=rtd.create_url(create_path),
+    )
+    resp = rtd.post(
+        create_path,
+        data=params,
+        headers=headers,
+    )
+    resp.raise_for_status()
+    ref = re.search(f'<a href="(.*?)">.*?webhook.*?</a>', resp.text).group(1)
+    return urllib.parse.urljoin(resp.url, ref)
+
+
+@autocommand.autocommand(__name__)
+def main(repo: Repo = Repo('.')):
+    create_project(repo)
+    url = configure_webhook(repo.name)
+    configure_github(repo.name, url)

docs/.rstcheck.cfg

@@ -1,4 +1,4 @@
 [rstcheck]
-ignore_directives=automodule,http:get
+ignore_directives=automodule,http:get,tabs,tab
 ignore_roles=djangosetting,setting
 ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced)

docs/api/v2.rst

@@ -253,6 +253,7 @@ Build list
     :>json array results: Array of ``Build`` objects.
 
     :query string project__slug: Narrow to builds for a specific ``Project``
+    :query string commit: Narrow to builds for a specific ``commit``
 
 Build detail
 ++++++++++++

docs/conf.py

@@ -27,6 +27,7 @@
     'sphinxcontrib.httpdomain',
     'djangodocs',
     'doc_extensions',
+    'sphinx_tabs.tabs',
 ]
 templates_path = ['_templates']
 

docs/design.rst

@@ -51,4 +51,10 @@ There's not a hard browser range, but your design changes should work reasonably
 browsers, IE8+ -- that's not to say it needs to be pixel-perfect in older browsers! Just avoid
 making changes that render older browsers utterly unusable (or provide a sane fallback).
 
+Brand Guidelines
+----------------
+
+Find our branding guidelines in our guidelines documentation: https://read-the-docs-guidelines.readthedocs-hosted.com.
+
 .. _Read the Docs GitHub project: https://github.com/rtfd/readthedocs.org/pulls
+

docs/faq.rst

@@ -70,9 +70,9 @@ I get import errors on libraries that depend on C modules
 .. note::
     Another use case for this is when you have a module with a C extension.
 
-This happens because our build system doesn't have the dependencies for building your project. This happens with things like libevent and mysql, and other python things that depend on C libraries. We can't support installing random C binaries on our system, so there is another way to fix these imports.
+This happens because our build system doesn't have the dependencies for building your project. This happens with things like ``libevent``, ``mysql``, and other python packages that depend on C libraries. We can't support installing random C binaries on our system, so there is another way to fix these imports.
 
-You can mock out the imports for these modules in your ``conf.py`` with the following snippet::
+With Sphinx you can use the built-in `autodoc_mock_imports`_ for mocking. Alternatively you can use the mock library by putting the following snippet in your ``conf.py``::
 
     import sys
     from unittest.mock import MagicMock
@@ -85,7 +85,7 @@ You can mock out the imports for these modules in your ``conf.py`` with the foll
     MOCK_MODULES = ['pygtk', 'gtk', 'gobject', 'argparse', 'numpy', 'pandas']
     sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 
-Of course, replacing `MOCK_MODULES` with the modules that you want to mock out.
+You need to replace ``MOCK_MODULES`` with the modules that you want to mock out.
 
 .. Tip:: The library ``unittest.mock`` was introduced on python 3.3. On earlier versions install the ``mock`` library
     from PyPI with (ie ``pip install mock``) and replace the above import::
@@ -94,6 +94,8 @@ Of course, replacing `MOCK_MODULES` with the modules that you want to mock out.
 
 If such libraries are installed via ``setup.py``, you also will need to remove all the C-dependent libraries from your ``install_requires`` in the RTD environment.
 
+.. _autodoc_mock_imports: http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports
+
 `Client Error 401` when building documentation
 ----------------------------------------------