Merge pull request readthedocs#3408 from rtfd/humitos/tox/fix-lint

Pin pylint to 1.7.5 and fix docstring styling

Author: ericholscher

prospector.yml

@@ -35,6 +35,15 @@ pep257:
     - D105
     - D211
     - D104
+    - D212  # Multi-line docstring summary should start at the first line
+    - D107  # Missing docstring in __init__
+    - D106  # Missing docstring in public nested class
+
+    # pydocstyle
+    - D406  # Section name should end with a newline ('Examples', not 'Examples::')
+    - D407  # Missing dashed underline after section ('Examples')
+    - D412  # No blank lines allowed between a section header and its content ('Examples')
+    - D413  # Missing blank line after last section ('Examples')
 
 pyflakes:
   disable:

readthedocs/builds/managers.py

@@ -16,7 +16,8 @@
 
 class VersionManagerBase(models.Manager):
 
-    """Version manager for manager only queries
+    """
+    Version manager for manager only queries.
 
     For queries not suitable for the :py:cls:`VersionQuerySet`, such as create
     queries.

readthedocs/builds/syncers.py

@@ -1,7 +1,8 @@
-"""Classes to copy files between build and web servers
+"""
+Classes to copy files between build and web servers.
 
-"Syncers" copy files from the local machine, while "Pullers" copy files to
-the local machine.
+"Syncers" copy files from the local machine, while "Pullers" copy files to the
+local machine.
 """
 
 from __future__ import absolute_import

readthedocs/builds/version_slug.py

@@ -1,4 +1,5 @@
-"""Contains logic for handling version slugs.
+"""
+Contains logic for handling version slugs.
 
 Handling slugs for versions is not too straightforward. We need to allow some
 characters which are uncommon in usual slugs. They are dots and underscores.
@@ -32,8 +33,8 @@ def get_fields_with_model(cls):
     """
     Replace deprecated function of the same name in Model._meta.
 
-    This replaces deprecated function (as of Django 1.10) in
-    Model._meta as prescrived in the Django docs.
+    This replaces deprecated function (as of Django 1.10) in Model._meta as
+    prescrived in the Django docs.
     https://docs.djangoproject.com/en/1.11/ref/models/meta/#migrating-from-the-old-api
     """
     return [

readthedocs/core/admin.py

@@ -1,4 +1,4 @@
-"""Django admin interface for core models"""
+"""Django admin interface for core models."""
 
 from __future__ import absolute_import
 from datetime import datetime, timedelta
@@ -22,7 +22,7 @@ class UserProjectInline(admin.TabularInline):
 
 class UserProjectFilter(admin.SimpleListFilter):
 
-    """Filter users based on project properties"""
+    """Filter users based on project properties."""
 
     parameter_name = 'project_state'
     title = _('user projects')
@@ -39,7 +39,8 @@ def lookups(self, request, model_admin):
         )
 
     def queryset(self, request, queryset):
-        """Add filters to queryset filter
+        """
+        Add filters to queryset filter.
 
         ``PROJECT_ACTIVE`` and ``PROJECT_BUILT`` look for versions on projects,
         ``PROJECT_RECENT`` looks for projects with builds in the last year

readthedocs/core/middleware.py

@@ -31,10 +31,11 @@
 
 class SubdomainMiddleware(object):
 
-    """Middleware to display docs for non-dashboard domains"""
+    """Middleware to display docs for non-dashboard domains."""
 
     def process_request(self, request):
-        """Process requests for unhandled domains
+        """
+        Process requests for unhandled domains.
 
         If the request is not for our ``PUBLIC_DOMAIN``, or if ``PUBLIC_DOMAIN``
         is not set and the request is for a subdomain on ``PRODUCTION_DOMAIN``,
@@ -132,22 +133,22 @@ def process_request(self, request):
 
 class SingleVersionMiddleware(object):
 
-    """Reset urlconf for requests for 'single_version' docs.
-
-    In settings.MIDDLEWARE_CLASSES, SingleVersionMiddleware must follow
-    after SubdomainMiddleware.
+    """
+    Reset urlconf for requests for 'single_version' docs.
 
+    In settings.MIDDLEWARE_CLASSES, SingleVersionMiddleware must follow after
+    SubdomainMiddleware.
     """
 
     def _get_slug(self, request):
-        """Get slug from URLs requesting docs.
+        """
+        Get slug from URLs requesting docs.
 
         If URL is like '/docs/<project_name>/', we split path
         and pull out slug.
 
         If URL is subdomain or CNAME, we simply read request.slug, which is
         set by SubdomainMiddleware.
-
         """
         slug = None
         if hasattr(request, 'slug'):
@@ -187,16 +188,16 @@ def process_request(self, request):
 class ProxyMiddleware(object):
 
     """
-    Middleware that sets REMOTE_ADDR based on HTTP_X_FORWARDED_FOR, if the
+    Middleware that sets REMOTE_ADDR based on HTTP_X_FORWARDED_FOR, if the.
 
     latter is set. This is useful if you're sitting behind a reverse proxy that
-    causes each request's REMOTE_ADDR to be set to 127.0.0.1.
-    Note that this does NOT validate HTTP_X_FORWARDED_FOR. If you're not behind
-    a reverse proxy that sets HTTP_X_FORWARDED_FOR automatically, do not use
-    this middleware. Anybody can spoof the value of HTTP_X_FORWARDED_FOR, and
-    because this sets REMOTE_ADDR based on HTTP_X_FORWARDED_FOR, that means
-    anybody can "fake" their IP address. Only use this when you can absolutely
-    trust the value of HTTP_X_FORWARDED_FOR.
+    causes each request's REMOTE_ADDR to be set to 127.0.0.1. Note that this
+    does NOT validate HTTP_X_FORWARDED_FOR. If you're not behind a reverse proxy
+    that sets HTTP_X_FORWARDED_FOR automatically, do not use this middleware.
+    Anybody can spoof the value of HTTP_X_FORWARDED_FOR, and because this sets
+    REMOTE_ADDR based on HTTP_X_FORWARDED_FOR, that means anybody can "fake"
+    their IP address. Only use this when you can absolutely trust the value of
+    HTTP_X_FORWARDED_FOR.
     """
 
     def process_request(self, request):

readthedocs/core/resolver.py

@@ -1,4 +1,4 @@
-"""URL resolver for documentation"""
+"""URL resolver for documentation."""
 
 from __future__ import absolute_import
 from builtins import object
@@ -54,7 +54,7 @@ class ResolverBase(object):
     def base_resolve_path(self, project_slug, filename, version_slug=None,
                           language=None, private=False, single_version=None,
                           subproject_slug=None, subdomain=None, cname=None):
-        """Resolve a with nothing smart, just filling in the blanks"""
+        """Resolve a with nothing smart, just filling in the blanks."""
         # Only support `/docs/project' URLs outside our normal environment. Normally
         # the path should always have a subdomain or CNAME domain
         # pylint: disable=unused-argument
@@ -80,7 +80,7 @@ def base_resolve_path(self, project_slug, filename, version_slug=None,
     def resolve_path(self, project, filename='', version_slug=None,
                      language=None, single_version=None, subdomain=None,
                      cname=None, private=None):
-        """Resolve a URL with a subset of fields defined"""
+        """Resolve a URL with a subset of fields defined."""
         relation = project.superprojects.first()
         cname = cname or project.domains.filter(canonical=True).first()
         main_language_project = project.main_language_project
@@ -145,7 +145,8 @@ def resolve(self, project, protocol='http', filename='', private=None,
         )
 
     def _get_canonical_project(self, project):
-        """Get canonical project in the case of subproject or translations
+        """
+        Get canonical project in the case of subproject or translations.
 
         :type project: Project
         :rtype: Project
@@ -159,7 +160,7 @@ def _get_canonical_project(self, project):
         return project
 
     def _get_project_subdomain(self, project):
-        """Determine canonical project domain as subdomain"""
+        """Determine canonical project domain as subdomain."""
         public_domain = getattr(settings, 'PUBLIC_DOMAIN', None)
         if self._use_subdomain():
             project = self._get_canonical_project(project)
@@ -177,9 +178,10 @@ def _get_private(self, project, version_slug):
 
     def _fix_filename(self, project, filename):
         """
-        Force filenames that might be HTML file paths into proper URL's
+        Force filenames that might be HTML file paths into proper URL's.
 
-        This basically means stripping / and .html endings and then re-adding them properly.
+        This basically means stripping / and .html endings and then re-adding
+        them properly.
         """
         # Bail out on non-html files
         if '.' in filename and '.html' not in filename:
@@ -203,7 +205,7 @@ def _fix_filename(self, project, filename):
         return path
 
     def _use_subdomain(self):
-        """Make decision about whether to use a subdomain to serve docs"""
+        """Make decision about whether to use a subdomain to serve docs."""
         use_subdomain = getattr(settings, 'USE_SUBDOMAIN', False)
         public_domain = getattr(settings, 'PUBLIC_DOMAIN', None)
         return use_subdomain and public_domain is not None

readthedocs/core/settings.py

@@ -1,4 +1,4 @@
-"""Class based settings for complex settings inheritance"""
+"""Class based settings for complex settings inheritance."""
 
 from __future__ import absolute_import
 from builtins import object
@@ -8,11 +8,12 @@
 
 class Settings(object):
 
-    """Class-based settings wrapper"""
+    """Class-based settings wrapper."""
 
     @classmethod
     def load_settings(cls, module_name):
-        """Export class variables and properties to module namespace
+        """
+        Export class variables and properties to module namespace.
 
         This will export and class variable that is all upper case and doesn't
         begin with ``_``. These members will be set as attributes on the module

readthedocs/core/symlink.py

@@ -50,7 +50,6 @@
             ja/
 
         fabric -> rtd-builds/fabric/en/latest/ # single version
-
 """
 
 from __future__ import absolute_import
@@ -121,9 +120,8 @@ def run(self):
         """
         Create proper symlinks in the right order.
 
-        Since we have a small nest of directories and symlinks,
-        the ordering of these calls matter,
-        so we provide this helper to make life easier.
+        Since we have a small nest of directories and symlinks, the ordering of
+        these calls matter, so we provide this helper to make life easier.
         """
         # Outside of the web root
         self.symlink_cnames()
@@ -138,7 +136,8 @@ def run(self):
             self.symlink_versions()
 
     def symlink_cnames(self, domain=None):
-        """Symlink project CNAME domains
+        """
+        Symlink project CNAME domains.
 
         Link from HOME/$CNAME_ROOT/<cname> ->
                   HOME/$WEB_ROOT/<project>
@@ -164,13 +163,14 @@ def symlink_cnames(self, domain=None):
             run(['ln', '-nsf', self.project.doc_path, project_cname_symlink])
 
     def remove_symlink_cname(self, domain):
-        """Remove CNAME symlink"""
+        """Remove CNAME symlink."""
         self._log(u"Removing symlink for CNAME {0}".format(domain.domain))
         symlink = os.path.join(self.CNAME_ROOT, domain.domain)
         os.unlink(symlink)
 
     def symlink_subprojects(self):
-        """Symlink project subprojects
+        """
+        Symlink project subprojects.
 
         Link from $WEB_ROOT/projects/<project> ->
                   $WEB_ROOT/<project>
@@ -213,7 +213,8 @@ def symlink_subprojects(self):
                     os.unlink(os.path.join(self.subproject_root, subproj))
 
     def symlink_translations(self):
-        """Symlink project translations
+        """
+        Symlink project translations.
 
         Link from $WEB_ROOT/<project>/<language>/ ->
                   $WEB_ROOT/<translation>/<language>/
@@ -247,7 +248,8 @@ def symlink_translations(self):
                     shutil.rmtree(to_delete)
 
     def symlink_single_version(self):
-        """Symlink project single version
+        """
+        Symlink project single version.
 
         Link from $WEB_ROOT/<project> ->
                   HOME/user_builds/<project>/rtd-builds/latest/
@@ -268,7 +270,8 @@ def symlink_single_version(self):
             run(['ln', '-nsf', docs_dir, symlink])
 
     def symlink_versions(self):
-        """Symlink project's versions
+        """
+        Symlink project's versions.
 
         Link from $WEB_ROOT/<project>/<language>/<version>/ ->
                   HOME/user_builds/<project>/rtd-builds/<version>
@@ -295,7 +298,7 @@ def symlink_versions(self):
                     os.unlink(os.path.join(version_dir, old_ver))
 
     def get_default_version(self):
-        """Look up project default version, return None if not found"""
+        """Look up project default version, return None if not found."""
         default_version = self.project.get_default_version()
         try:
             return self.get_version_queryset().get(slug=default_version)

readthedocs/core/tasks.py

@@ -1,4 +1,4 @@
-"""Basic tasks"""
+"""Basic tasks."""
 
 from __future__ import absolute_import
 import logging
@@ -19,7 +19,8 @@
 @app.task(queue='web', time_limit=EMAIL_TIME_LIMIT)
 def send_email_task(recipient, subject, template, template_html,
                     context=None, from_email=None, **kwargs):
-    """Send multipart email
+    """
+    Send multipart email.
 
     recipient
         Email recipient address

readthedocs/core/utils/__init__.py

@@ -1,4 +1,4 @@
-"""Common utilty functions"""
+"""Common utilty functions."""
 
 from __future__ import absolute_import
 
@@ -77,7 +77,8 @@ def cname_to_slug(host):
 
 
 def trigger_build(project, version=None, record=True, force=False, basic=False):
-    """Trigger build for project and version
+    """
+    Trigger build for project and version.
 
     If project has a ``build_queue``, execute task on this build queue. Queue
     will be prefixed with ``build-`` to unify build queue names.
@@ -135,7 +136,8 @@ def trigger_build(project, version=None, record=True, force=False, basic=False):
 
 def send_email(recipient, subject, template, template_html, context=None,
                request=None, from_email=None, **kwargs):  # pylint: disable=unused-argument
-    """Alter context passed in and call email send task
+    """
+    Alter context passed in and call email send task.
 
     .. seealso::
 
@@ -152,7 +154,8 @@ def send_email(recipient, subject, template, template_html, context=None,
 
 
 def slugify(value, *args, **kwargs):
-    """Add a DNS safe option to slugify
+    """
+    Add a DNS safe option to slugify.
 
     :param dns_safe: Remove underscores from slug as well
     """
@@ -170,9 +173,9 @@ def safe_makedirs(directory_name):
     """
     Safely create a directory.
 
-    Makedirs has an issue where it has a race condition around
-    checking for a directory and then creating it.
-    This catches the exception in the case where the dir already exists.
+    Makedirs has an issue where it has a race condition around checking for a
+    directory and then creating it. This catches the exception in the case where
+    the dir already exists.
     """
     try:
         os.makedirs(directory_name)