Merge remote-tracking branch 'origin/master' into add-docker-image-option

Author: ericholscher

.flake8

@@ -1,3 +1,3 @@
 [flake8]
-ignore = E125,D100,D101,D102,D105,D107,D200,D211,P101,FI15,FI16,FI12,FI11,FI17,FI50,FI53,FI54,T000,MQ101
+ignore = E125,D100,D101,D102,D103,D105,D106,D107,D200,D202,D211,P101,FI15,FI16,FI12,FI11,FI17,FI50,FI53,FI54,MQ101,T000
 max-line-length = 80

.pre-commit-config.yaml

@@ -26,6 +26,7 @@ repos:
       'flake8-string-format',
       'flake8-tidy-imports',
       'flake8-todo']
+      exclude: 'test_oauth.py'
     - id: trailing-whitespace
 
 - repo: [email protected]:pre-commit/mirrors-yapf.git
@@ -34,6 +35,7 @@ repos:
     - id: yapf
       exclude: 'migrations|settings|scripts'
       additional_dependencies: ['futures']
+      args: ['--style=.style.yapf', '--parallel']
 
 - repo: [email protected]:FalconSocial/pre-commit-python-sorter.git
   sha: b57843b0b874df1d16eb0bef00b868792cb245c2
@@ -52,3 +54,11 @@ repos:
   hooks:
     - id: autoflake
       args: ['--in-place', '--remove-all-unused-imports', '--remove-unused-variable']
+
+- repo: git://github.com/guykisel/prospector-mirror
+  sha: 'b27f281eb9398fc8504415d7fbdabf119ea8c5e1'
+  hooks:
+    - id: prospector
+      # https://github.com/pre-commit/pre-commit/issues/178
+      language: system
+      args: ['--profile=prospector']

.style.yapf

@@ -26,7 +26,7 @@ ALLOW_MULTILINE_DICTIONARY_KEYS=False
 #                      # <------ this blank line
 #     def method():
 #       ...
-BLANK_LINE_BEFORE_NESTED_CLASS_OR_DEF=True
+BLANK_LINE_BEFORE_NESTED_CLASS_OR_DEF=False
 
 # Insert a blank line before a class-level docstring.
 BLANK_LINE_BEFORE_CLASS_DOCSTRING=True
@@ -145,7 +145,7 @@ SPLIT_BEFORE_EXPRESSION_AFTER_OPENING_PAREN=True
 
 # If an argument / parameter list is going to be split, then split
 # before the first argument.
-SPLIT_BEFORE_FIRST_ARGUMENT=False
+SPLIT_BEFORE_FIRST_ARGUMENT=True
 
 # Set to True to prefer splitting before 'and' or 'or' rather than
 # after.

CHANGELOG.rst

@@ -0,0 +1,46 @@
+Version 2.1.0
+-------------
+
+ * `@ericholscher <http://github.com/ericholscher>`_: Revert "Merge pull request #3336 from rtfd/use-active-for-stable" (`#3368 <https://github.com/rtfd/readthedocs.org/pull/3368>`_)
+ * `@agjohnson <http://github.com/agjohnson>`_: Revert "Do not split before first argument (#3333)" (`#3366 <https://github.com/rtfd/readthedocs.org/pull/3366>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Remove pitch from ethical ads page, point folks to actual pitch page. (`#3365 <https://github.com/rtfd/readthedocs.org/pull/3365>`_)
+ * `@agjohnson <http://github.com/agjohnson>`_: Add changelog and changelog automation (`#3364 <https://github.com/rtfd/readthedocs.org/pull/3364>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Fix mkdocs search. (`#3361 <https://github.com/rtfd/readthedocs.org/pull/3361>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Email sending: Allow kwargs for other options (`#3355 <https://github.com/rtfd/readthedocs.org/pull/3355>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Try and get folks to put more tags. (`#3350 <https://github.com/rtfd/readthedocs.org/pull/3350>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Suggest wiping your environment to folks with bad build outcomes. (`#3347 <https://github.com/rtfd/readthedocs.org/pull/3347>`_)
+ * `@humitos <http://github.com/humitos>`_: GitLab Integration (`#3327 <https://github.com/rtfd/readthedocs.org/pull/3327>`_)
+ * `@jimfulton <http://github.com/jimfulton>`_: Draft policy for claiming existing project names. (`#3314 <https://github.com/rtfd/readthedocs.org/pull/3314>`_)
+ * `@agjohnson <http://github.com/agjohnson>`_: More logic changes to error reporting, cleanup (`#3310 <https://github.com/rtfd/readthedocs.org/pull/3310>`_)
+ * `@safwanrahman <http://github.com/safwanrahman>`_: [Fix #3182] Better user deletion (`#3214 <https://github.com/rtfd/readthedocs.org/pull/3214>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Better User deletion (`#3182 <https://github.com/rtfd/readthedocs.org/issues/3182>`_)
+ * `@RichardLitt <http://github.com/RichardLitt>`_: Add `Needed: replication` label (`#3138 <https://github.com/rtfd/readthedocs.org/pull/3138>`_)
+ * `@josejrobles <http://github.com/josejrobles>`_: Replaced usage of deprecated function get_fields_with_model with new … (`#3052 <https://github.com/rtfd/readthedocs.org/pull/3052>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Don't delete the subprojects directory on sync of superproject (`#3042 <https://github.com/rtfd/readthedocs.org/pull/3042>`_)
+ * `@andrew <http://github.com/andrew>`_: Pass query string when redirecting, fixes #2595 (`#3001 <https://github.com/rtfd/readthedocs.org/pull/3001>`_)
+ * `@saily <http://github.com/saily>`_: Add GitLab repo sync and webhook support (`#1870 <https://github.com/rtfd/readthedocs.org/pull/1870>`_)
+ * `@destroyerofbuilds <http://github.com/destroyerofbuilds>`_: Setup GitLab Web Hook on Project Import (`#1443 <https://github.com/rtfd/readthedocs.org/issues/1443>`_)
+ * `@takotuesday <http://github.com/takotuesday>`_: Add GitLab Provider from django-allauth (`#1441 <https://github.com/rtfd/readthedocs.org/issues/1441>`_)
+
+Version 2.0
+-----------
+
+ * `@ericholscher <http://github.com/ericholscher>`_: Email sending: Allow kwargs for other options (`#3355 <https://github.com/rtfd/readthedocs.org/pull/3355>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Try and get folks to put more tags. (`#3350 <https://github.com/rtfd/readthedocs.org/pull/3350>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Small changes to email sending to enable from email (`#3349 <https://github.com/rtfd/readthedocs.org/pull/3349>`_)
+ * `@dplanella <http://github.com/dplanella>`_: Duplicate TOC entries (`#3345 <https://github.com/rtfd/readthedocs.org/issues/3345>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Small tweaks to ethical ads page (`#3344 <https://github.com/rtfd/readthedocs.org/pull/3344>`_)
+ * `@agjohnson <http://github.com/agjohnson>`_: Fix python usage around oauth pagination (`#3342 <https://github.com/rtfd/readthedocs.org/pull/3342>`_)
+ * `@tony <http://github.com/tony>`_: Fix isort link (`#3340 <https://github.com/rtfd/readthedocs.org/pull/3340>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Change stable version switching to respect `active` (`#3336 <https://github.com/rtfd/readthedocs.org/pull/3336>`_)
+ * `@ericholscher <http://github.com/ericholscher>`_: Allow superusers to pass admin & member tests for projects (`#3335 <https://github.com/rtfd/readthedocs.org/pull/3335>`_)
+ * `@humitos <http://github.com/humitos>`_: Do not split before first argument (`#3333 <https://github.com/rtfd/readthedocs.org/pull/3333>`_)
+ * `@humitos <http://github.com/humitos>`_: Update docs for pre-commit (auto linting) (`#3332 <https://github.com/rtfd/readthedocs.org/pull/3332>`_)
+ * `@humitos <http://github.com/humitos>`_: Take preferece of tags over branches when selecting the stable version (`#3331 <https://github.com/rtfd/readthedocs.org/pull/3331>`_)
+ * `@humitos <http://github.com/humitos>`_: Add prospector as a pre-commit hook (`#3328 <https://github.com/rtfd/readthedocs.org/pull/3328>`_)
+ * `@andrewgodwin <http://github.com/andrewgodwin>`_: "stable" appearing to track future release branches (`#3268 <https://github.com/rtfd/readthedocs.org/issues/3268>`_)
+ * `@humitos <http://github.com/humitos>`_: Config files for auto linting (`#3264 <https://github.com/rtfd/readthedocs.org/pull/3264>`_)
+ * `@mekrip <http://github.com/mekrip>`_: Build is not working (`#3223 <https://github.com/rtfd/readthedocs.org/issues/3223>`_)
+ * `@skddc <http://github.com/skddc>`_: Add JSDoc to docs build environment (`#3069 <https://github.com/rtfd/readthedocs.org/issues/3069>`_)
+ * `@jakirkham <http://github.com/jakirkham>`_: Specifying conda version used (`#2076 <https://github.com/rtfd/readthedocs.org/issues/2076>`_)
+ * `@agjohnson <http://github.com/agjohnson>`_: Document code style guidelines (`#1475 <https://github.com/rtfd/readthedocs.org/issues/1475>`_)

contrib/changelog.hbs

@@ -0,0 +1,5 @@
+{{header}}
+{{toHeader header "-"}}
+
+{{#issues}} * `@{{user.login}} <http://github.com/{{user.login}}>`_: {{title}} (`#{{number}} <{{html_url}}>`_)
+{{/issues}}

docs/abandoned-projects.rst

@@ -0,0 +1,105 @@
+Policy for Abandoned Projects
+=============================
+
+This policy describes the process by which a Read the Docs project name may be changed.
+
+
+Rationale
+---------
+
+Conflict between the current use of the name and a different suggested use of
+the same name occasionally arise.  This document aims to provide general
+guidelines for solving the most typical cases of such conflicts.
+
+
+Specification
+-------------
+
+The main idea behind this policy is that Read the Docs serves the community.  Every
+user is invited to upload content under the Terms of Use, understanding that it
+is at the sole risk of the user.
+
+While Read the Docs is not a backup service, the maintainers do their best to keep that
+content accessible indefinitely in its published form.  However, in certain
+edge cases the greater community's needs might outweigh the individual's
+expectation of ownership of a project name.
+
+The use cases covered by this policy are:
+
+* Abandoned projects:
+
+    * renaming a project so that the original project name can be used by a
+      different project.
+
+* Active projects:
+
+    * resolving disputes over a name.
+
+
+Implementation
+--------------
+
+Reachability
+~~~~~~~~~~~~
+
+The user of Read the Docs is solely responsible for being reachable by the maintainers
+for matters concerning projects that the user owns.  In every case where
+contacting the user is necessary, the maintainers will try to do so at least
+three times, using the following means of contact:
+
+* e-mail address on file in the user's profile;
+* e-mail addresses found in the given project's documentation; and
+* e-mail address on the project's home page.
+
+The maintainers will stop trying to reach the user after six weeks and the user
+will be considered *unreachable*.
+
+
+Abandoned projects
+~~~~~~~~~~~~~~~~~~
+
+A project is considered *abandoned* when ALL of the following are met:
+
+* owner is unreachable (see Reachability above);
+* The project has no proper documentation being served (no successful builds); or
+* no releases within the past twelve months; and
+* no activity from the owner on the project's home page (or no home page
+  found).
+
+All other projects are considered *active*.
+
+
+Renaming of an abandoned project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Projects are never renamed solely on the basis of abandonment.
+
+An *abandoned* project can be renamed (by appending "-abandoned" and a
+uniquifying integer if needed) for purposes of reusing the name when ALL of the
+following are met:
+
+* the project has been determined *abandoned* by the rules described above;
+* the candidate is able to demonstrate their own failed attempts to contact the
+  existing owner;
+* the candidate is able to demonstrate that the project suggested to reuse the
+  name already exists and meets notability requirements;
+* the candidate is able to demonstrate why a fork under a different name is not
+  an acceptable workaround;
+* the project has fewer than 100 monthly pageviews; and
+* the maintainers do not have any additional reservations.
+
+
+Name conflict resolution for active projects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The maintainers of Read the Docs are not arbiters in disputes around *active* projects.
+The maintainers recommend users to get in touch with each other and solve the
+issue by respectful communication.
+
+
+Prior art
+---------
+
+The Python Package Index (PyPI) policy for claiming abandoned packages
+(`PEP-0541 <https://www.python.org/dev/peps/pep-0541>`_) heavily
+influenced this policy.

docs/changelog.md renamed to docs/changelog.rst

@@ -1,16 +1,25 @@
-# Changelog
+Changelog
+=========
 
-This document will track major changes in the project.
+.. include:: ../CHANGELOG.rst
 
-Also note, this document is a Markdown file. This is mainly to keep parity with GitHub, and also because we can.
+Previous releases
+-----------------
 
-## July 23, 2015
+Starting with version ``2.0``, we will be incrementing the Read the Docs version
+based on semantic versioning principles, and will be automating the update of
+our changelog.
 
+Below are some historical changes from when we have tried to add information
+here in the past
 
-* Django 1.8 Support Merged
+July 23, 2015
+~~~~~~~~~~~~~
 
-### Code Notes
+* Django 1.8 Support Merged
 
+Code Notes
+``````````
 
 - Updated Django from `1.6.11` to `1.8.3`.
 - Removed South and ported the South migrations to Django's migration framework.
@@ -25,36 +34,32 @@ Also note, this document is a Markdown file. This is mainly to keep parity with
 - Added `django.setup()` to `conf.py` to load django properly for doc builds.
 - Added migrations for all apps with models in the `readthedocs/` directory
 
-### Deployment Notes
+Deployment Notes
+````````````````
 
-After you have updated the code and installed the new dependencies, you need to run these commands on the server:
+After you have updated the code and installed the new dependencies, you need to run these commands on the server::
 
-```bash
-python manage.py migrate contenttypes
-python manage.py migrate projects 0002 --fake
-python manage.py migrate --fake-initial
-```
+    python manage.py migrate contenttypes
+    python manage.py migrate projects 0002 --fake
+    python manage.py migrate --fake-initial
 
 Locally I had trouble in a test environment that pip did not update to the specified commit of tastypie. It might be required to use `pip install -U -r requirements/deploy.txt` during deployment.
 
 
-### Development Update Notes
+Development Update Notes
+````````````````````````
 
 The readthedocs developers need to execute these commands when switching to this branch (or when this got merged into master):
 
-- **Before updating** please make sure that all migrations are applied:
+- **Before updating** please make sure that all migrations are applied::
 
-```bash
-python manage.py syncdb
-python manage.py migrate
-```
+    python manage.py syncdb
+    python manage.py migrate
 
 - Update the codebase: `git pull`
 - You need to update the requirements with `pip install -r requirements.txt`
-- Now you need to fake the initial migrations:
+- Now you need to fake the initial migrations::
 
-```bash
-python manage.py migrate contenttypes
-python manage.py migrate projects 0002 --fake
-python manage.py migrate --fake-initial
-```
+    python manage.py migrate contenttypes
+    python manage.py migrate projects 0002 --fake
+    python manage.py migrate --fake-initial

docs/contribute.rst

@@ -34,26 +34,49 @@ label. Those tickets are meant to be standalone and can be worked on ad-hoc.
 When contributing code, then please follow the standard Contribution
 Guidelines set forth at `contribution-guide.org`_.
 
-We have a strict code style that it's easy to follow since you just
-have to run a couple of commands and they will do everything for
-you. These commands are a mix between `autoflake`_, `autopep8`_,
-`docformatter`_, `isort`_, `unify`_ and `yapf`_::
-
-  $ autoflake --remove-all-unused-imports --remove-unused-variables --keep-useless-pass
-  $ autopep8
-  $ docformatter --wrap-summaries=80 --wrap-descriptions=80 --pre-summary-newline --no-blank
-  $ isort
-  $ unify --quote="'"
-  $ yapf --exclude=*migrations* --exclude=*settings* --exclude=*scripts* --parallel
+We have a strict code style that is easy to follow since you just have to
+install `pre-commit`_ and it will automatically run different linting tools
+(`autoflake`_, `autopep8`_, `docformatter`_, `isort`_, `prospector`_, `unify`_
+and `yapf`_) to check your changes before you commit them. `pre-commit` will let
+you know if there were any problems that is wasn't able to fix automatically.
+
+To run the `pre-commit` command and check your changes::
+
+    $ pip install -U pre-commit
+    $ git add <your-modified-files>
+    $ pre-commit run
+
+or to run against a specific file::
+
+    $ pre-commit run --files <file.py>
+
+`pre-commit` can also be run as a git pre-commit hook. You can set this up
+with::
+
+    $ pre-commit install
+
+After this installation, the next time you run `git commit` the `pre-commit run`
+command will be run immediately and will inform you of the changes and errors.
+
+.. note::
+
+    Our code base is still maturing and the core team doesn't yet recommend
+    running this as a pre-commit hook due to the number of changes this will
+    cause while constructing a pull request. Independent pull requests with
+    linting changes would be a great help to making this possible.
+
 
 .. _Feature Overview: https://github.com/rtfd/readthedocs.org/issues?direction=desc&labels=Feature+Overview&page=1&sort=updated&state=open
 .. _Good First Issue: https://github.com/rtfd/readthedocs.org/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22
 .. _Sprintable: https://github.com/rtfd/readthedocs.org/issues?q=is%3Aopen+is%3Aissue+label%3ASprintable
 .. _contribution-guide.org: http://www.contribution-guide.org/#submitting-bugs
 
+.. _pre-commit: https://github.com/pre-commit/pre-commit
 .. _autoflake: https://github.com/myint/autoflake
 .. _autopep8: https://github.com/hhatto/autopep8
 .. _docformatter: https://github.com/myint/docformatter
+.. _isort: https://github.com/timothycrosley/isort
+.. _prospector: https://prospector.landscape.io/en/master
 .. _unify: https://github.com/myint/unify
 .. _yapf: https://github.com/google/yapf