Lint (pep257: D415)

readthedocs/api/v2/views/integrations.py

@@ -223,7 +223,8 @@ def is_payload_valid(self):
         GitHub use a HMAC hexdigest hash to sign the payload.
 
         It is sent in the request's header.
-        See https://developer.github.com/webhooks/securing/
+
+        See https://developer.github.com/webhooks/securing/.
         """
         signature = self.request.META.get(GITHUB_SIGNATURE_HEADER)
         secret = self.get_integration().secret
@@ -245,7 +246,7 @@ def is_payload_valid(self):
 
     @staticmethod
     def get_digest(secret, msg):
-        """Get a HMAC digest of `msg` using `secret.`"""
+        """Get a HMAC digest of `msg` using `secret`."""
         digest = hmac.new(
             secret.encode(),
             msg=msg.encode(),

readthedocs/builds/querysets.py

@@ -121,7 +121,7 @@ class BuildQuerySet(SettingsOverrideObject):
 
 class RelatedBuildQuerySetBase(models.QuerySet):
 
-    """For models with association to a project through :py:class:`Build`"""
+    """For models with association to a project through :py:class:`Build`."""
 
     use_for_related_fields = True
 

readthedocs/builds/storage.py

@@ -12,7 +12,7 @@
 class BuildMediaStorageMixin:
 
     """
-    A mixin for Storage classes needed to write build artifacts
+    A mixin for Storage classes needed to write build artifacts.
 
     This adds and modifies some functionality to Django's File Storage API.
     By default, classes mixing this in will now overwrite files by default instead
@@ -24,7 +24,11 @@ class BuildMediaStorageMixin:
 
     @staticmethod
     def _dirpath(path):
-        """It may just be Azure, but for listdir to work correctly, the path must end in '/'"""
+        """
+        Make the path to end with `/`.
+
+        It may just be Azure, but for listdir to work correctly, this is needed.
+        """
         path = str(path)
         if not path.endswith('/'):
             path += '/'
@@ -33,7 +37,7 @@ def _dirpath(path):
 
     def get_available_name(self, name, max_length=None):
         """
-        Overrides Django's storage implementation to always return the passed name (overwrite)
+        Overrides Django's storage to always return the passed name (overwrite).
 
         By default, Django will not overwrite files even if the same name is specified.
         This changes that functionality so that the default is to use the same name and overwrite
@@ -43,7 +47,7 @@ def get_available_name(self, name, max_length=None):
 
     def delete_directory(self, path):
         """
-        Delete all files under a certain path from storage
+        Delete all files under a certain path from storage.
 
         Many storage backends (S3, Azure storage) don't care about "directories".
         The directory effectively doesn't exist if there are no files in it.
@@ -67,7 +71,7 @@ def delete_directory(self, path):
 
     def copy_directory(self, source, destination):
         """
-        Copy a directory recursively to storage
+        Copy a directory recursively to storage.
 
         :param source: the source path on the local disk
         :param destination: the destination path in storage
@@ -86,11 +90,11 @@ def copy_directory(self, source, destination):
 
 class BuildMediaFileSystemStorage(BuildMediaStorageMixin, FileSystemStorage):
 
-    """Storage subclass that writes build artifacts under MEDIA_ROOT"""
+    """Storage subclass that writes build artifacts under MEDIA_ROOT."""
 
     def get_available_name(self, name, max_length=None):
         """
-        A hack to overwrite by default with the FileSystemStorage
+        A hack to overwrite by default with the FileSystemStorage.
 
         After upgrading to Django 2.2, this method can be removed
         because subclasses can set OS_OPEN_FLAGS such that FileSystemStorage._save
@@ -103,7 +107,11 @@ def get_available_name(self, name, max_length=None):
         return name
 
     def listdir(self, path):
-        """Return empty lists for nonexistent directories (as cloud storages do)"""
+        """
+        Return empty lists for nonexistent directories.
+
+        This mimics what cloud storages do.
+        """
         if not self.exists(path):
             return [], []
         return super().listdir(path)

readthedocs/builds/syncers.py

@@ -29,7 +29,7 @@ def copy(cls, path, target, is_file=False, **kwargs):
 
 class NullSyncer:
 
-    """A syncer that doesn't actually do anything"""
+    """A syncer that doesn't actually do anything."""
 
     @classmethod
     def copy(cls, path, target, is_file=False, **kwargs):

readthedocs/core/templatetags/core_tags.py

@@ -117,7 +117,7 @@ def readthedocs_version():
 @register.filter
 def escapejson(data, indent=None):
     """
-    Escape JSON correctly for inclusion in Django templates
+    Escape JSON correctly for inclusion in Django templates.
 
     This code was mostly taken from Django's implementation
     https://docs.djangoproject.com/en/2.2/ref/templates/builtins/#json-script

readthedocs/core/views/__init__.py

@@ -1,7 +1,8 @@
 """
-Core views, including the main homepage,
+Core views.
 
-documentation and header rendering, and server errors.
+Including the main homepage, documentation and header rendering,
+and server errors.
 """
 
 import os

readthedocs/oauth/querysets.py

@@ -9,7 +9,7 @@
 
 class RelatedUserQuerySetBase(models.QuerySet):
 
-    """For models with relations through :py:class:`User`"""
+    """For models with relations through :py:class:`User`."""
 
     def api(self, user=None):
         """Return objects for user."""

readthedocs/projects/models.py

@@ -1039,7 +1039,11 @@ def remove_subproject(self, child):
         ProjectRelationship.objects.filter(parent=self, child=child).delete()
 
     def get_parent_relationship(self):
-        """Get the parent project relationship or None if this is a top level project"""
+        """
+        Get parent project relationship.
+
+        It returns ``None`` if this is a top level project.
+        """
         if hasattr(self, '_superprojects'):
             # Cached parent project relationship
             if self._superprojects:
@@ -1154,7 +1158,7 @@ def has_feature(self, feature_id):
 
     @property
     def show_advertising(self):
-        """Whether this project is ad-free (don't access the database)"""
+        """Whether this project is ad-free (don't access the database)."""
         return not self.ad_free
 
     @property

readthedocs/projects/querysets.py

@@ -77,9 +77,11 @@ def is_active(self, project):
 
     def prefetch_latest_build(self):
         """
-        For a given queryset of projects, prefetch the latest build for each project
+        Prefetch "latest build" for each project.
 
-        This should come after any filtering.
+        .. note::
+
+            This should come after any filtering.
         """
         from readthedocs.builds.models import Build
 
@@ -99,7 +101,7 @@ def prefetch_latest_build(self):
     # Aliases
 
     def dashboard(self, user=None):
-        """Get the projects for this user including the latest build"""
+        """Get the projects for this user including the latest build."""
         return self.for_admin_user(user).prefetch_latest_build()
 
     def api(self, user=None, detail=True):

readthedocs/projects/tasks.py

@@ -703,7 +703,7 @@ def store_build_artifacts(
             epub=False,
     ):
         """
-        Save build artifacts to "storage" using Django's storage API
+        Save build artifacts to "storage" using Django's storage API.
 
         The storage could be local filesystem storage OR cloud blob storage
         such as S3, Azure storage or Google Cloud Storage.
@@ -1688,7 +1688,7 @@ def remove_dirs(paths):
 @app.task(queue='web')
 def remove_build_storage_paths(paths):
     """
-    Remove artifacts from build media storage (cloud or local storage)
+    Remove artifacts from build media storage (cloud or local storage).
 
     :param paths: list of paths in build media storage to delete
     """

readthedocs/projects/views/public.py

@@ -70,7 +70,12 @@ def get_context_data(self, **kwargs):
 
 
 def project_redirect(request, invalid_project_slug):
-    """Redirect old project slugs that had underscores which are no longer allowed"""
+    """
+    Redirect project slugs that have underscores (``_``).
+
+    Slugs with underscores are no longer allowed.
+    Underscores are replaced by ``-`` and then redirected to that URL.
+    """
     new_project_slug = invalid_project_slug.replace('_', '-')
     new_path = request.path.replace(invalid_project_slug, new_project_slug)
     return redirect('{}?{}'.format(

readthedocs/search/utils.py

@@ -104,7 +104,7 @@ def get_chunk(total, chunk_size):
 
 def _get_index(indices, index_name):
     """
-    Get Index from all the indices
+    Get Index from all the indices.
 
     :param indices: DED indices list
     :param index_name: Name of the index
@@ -117,7 +117,7 @@ def _get_index(indices, index_name):
 
 def _get_document(model, document_class):
     """
-    Get DED document class object from the model and name of document class
+    Get DED document class object from the model and name of document class.
 
     :param model: The model class to find the document
     :param document_class: the name of the document class.

readthedocs/search/views.py

@@ -36,7 +36,7 @@
 
 def elastic_search(request, project_slug=None):
     """
-    Global user search on the dashboard
+    Global user search on the dashboard.
 
     This is for both the main search and project search.
 

readthedocs/vcs_support/backends/bzr.py

@@ -49,7 +49,9 @@ def tags(self):
 
     def parse_tags(self, data):
         """
-        Parses output of bzr tags, eg:
+        Parses output of bzr tags.
+
+        Example:
 
             0.1.0                171
             0.1.1                173

readthedocs/vcs_support/backends/hg.py

@@ -51,7 +51,9 @@ def branches(self):
 
     def parse_branches(self, data):
         """
-        Parses output of `hg branches --quiet`, eg:
+        Parses output of `hg branches --quiet`.
+
+        Example:
 
             default
             0.2
@@ -73,7 +75,9 @@ def tags(self):
 
     def parse_tags(self, data):
         """
-        Parses output of `hg tags`, eg:
+        Parses output of `hg tags`.
+
+        Example:
 
             tip                              278:c4b2d21db51a
             0.2.2                            152:6b0364d98837

readthedocs/vcs_support/backends/svn.py

@@ -78,7 +78,9 @@ def tags(self):
 
     def parse_tags(self, data):
         """
-        Parses output of svn list, eg:
+        Parses output of svn list.
+
+        Example:
 
         release-1.1/
         release-1.2/