Merge pull request #2729 from getnikola/adjusting-to-new-pydocstyle-rules

Kwpolska · web-flow · commit c8a5ffd762dc · 2017-04-19T20:49:27.000+02:00
Fixing docstrings so the new version of pydocstyle likes them.
diff --git a/nikola/nikola.py b/nikola/nikola.py
@@ -389,7 +389,7 @@ class Nikola(object):
     """
 
     def __init__(self, **config):
-        """Setup proper environment for running tasks."""
+        """Initialize proper environment for running tasks."""
         # Register our own path handlers
         self.path_handlers = {
             'slug': self.slug_path,
@@ -1873,7 +1873,7 @@ def root_path(self, name, lang):
             return []
 
     def slug_path(self, name, lang):
-        """A link to a post with given slug, if not ambiguous.
+        """Return a link to a post with given slug, if not ambiguous.
 
         Example:
 
@@ -2180,7 +2180,7 @@ def scan_posts(self, really=False, ignore_quit=False, quiet=False):
         signal('scanned').send(self)
 
     def generic_renderer(self, lang, output_name, template_name, filters, file_deps=None, uptodate_deps=None, context=None, context_deps_remove=None, post_deps_dict=None, url_type=None, is_fragment=False):
-        """Helper function for rendering pages and post lists and other related pages.
+        """Create tasks for rendering pages and post lists and other related pages.
 
         lang is the current language.
         output_name is the destination file name.
diff --git a/nikola/plugin_categories.py b/nikola/plugin_categories.py
@@ -325,7 +325,7 @@ def create_post(self, path, content=None, onefile=False, is_page=False, **kw):
         raise NotImplementedError()
 
     def extension(self):
-        """The preferred extension for the output of this compiler."""
+        """Return the preferred extension for the output of this compiler."""
         return ".html"
 
     def read_metadata(self, post, file_metadata_regexp=None, unslugify_titles=False, lang=None):
@@ -690,9 +690,10 @@ def get_classification_friendly_name(self, classification, lang, only_last_compo
         raise NotImplementedError()
 
     def get_overview_path(self, lang, dest_type='page'):
-        """A path handler for the classification overview.
+        """Return path for classification overview.
 
-        Must return one or two values (in this order):
+        This path handler for the classification overview must return one or
+        two values (in this order):
          * a list or tuple of strings: the path relative to OUTPUT_DIRECTORY;
          * a string with values 'auto', 'always' or 'never', indicating whether
            INDEX_FILE should be added or not.
@@ -710,9 +711,10 @@ def get_overview_path(self, lang, dest_type='page'):
         raise NotImplementedError()
 
     def get_path(self, classification, lang, dest_type='page'):
-        """A path handler for the given classification.
+        """Return path to the classification page.
 
-        Must return one to three values (in this order):
+        This path handler for the given classification must return one to
+        three values (in this order):
          * a list or tuple of strings: the path relative to OUTPUT_DIRECTORY;
          * a string with values 'auto', 'always' or 'never', indicating whether
            INDEX_FILE should be added or not;
diff --git a/nikola/plugins/command/serve.py b/nikola/plugins/command/serve.py
@@ -203,9 +203,9 @@ def log_message(self, *args):
     # Note that it might break in future versions of Python, in which case we
     # would need to do even more magic.
     def send_head(self):
-        """Common code for GET and HEAD commands.
+        """Send response code and MIME header.
 
-        This sends the response code and MIME headers.
+        This is common code for GET and HEAD commands.
 
         Return value is either a file object (which has to be copied
         to the outputfile by the caller unless the command was HEAD,
diff --git a/nikola/plugins/compile/markdown/mdx_podcast.py b/nikola/plugins/compile/markdown/mdx_podcast.py
@@ -69,7 +69,7 @@ def handleMatch(self, m):
 
 
 class PodcastExtension(MarkdownExtension, Extension):
-    """"Podcast extension for Markdown."""
+    """Podcast extension for Markdown."""
 
     def __init__(self, configs={}):
         """Initialize extension."""
diff --git a/nikola/plugins/compile/rest/__init__.py b/nikola/plugins/compile/rest/__init__.py
@@ -203,7 +203,7 @@ def new_document(self):
 
 def shortcode_role(name, rawtext, text, lineno, inliner,
                    options={}, content=[]):
-    """A shortcode role that passes through raw inline HTML."""
+    """Return a shortcode role that passes through raw inline HTML."""
     return [docutils.nodes.raw('', text, format='html')], []
 
 
@@ -270,7 +270,7 @@ def rst2html(source, source_path=None, source_class=docutils.io.StringInput,
 
         publish_parts(..., settings_overrides={'input_encoding': 'unicode'})
 
-    Parameters: see `publish_programmatically`.
+    For a description of the parameters, see `publish_programmatically`.
 
     WARNING: `reader` should be None (or NikolaReader()) if you want Nikola to report
              reStructuredText syntax errors.
diff --git a/nikola/plugins/compile/rest/listing.py b/nikola/plugins/compile/rest/listing.py
@@ -204,5 +204,8 @@ def get_code_from_file(self, data):
         return super(Listing, self).run()
 
     def assert_has_content(self):
-        """Listing has no content, override check from superclass."""
+        """Override check from superclass with nothing.
+
+        Listing has no content, override check from superclass.
+        """
         pass
diff --git a/nikola/plugins/task/archive.py b/nikola/plugins/task/archive.py
@@ -132,7 +132,7 @@ def get_classification_friendly_name(self, classification, lang, only_last_compo
                 return self.site.MESSAGES[lang]['{month} {day}, {year}'].format(year=year, month=month, day=day)
 
     def get_path(self, classification, lang, dest_type='page'):
-        """A path handler for the given classification."""
+        """Return a path for the given classification."""
         components = [self.site.config['ARCHIVE_PATH']]
         if classification:
             components.extend(classification)
diff --git a/nikola/plugins/task/authors.py b/nikola/plugins/task/authors.py
@@ -94,11 +94,11 @@ def get_classification_friendly_name(self, author, lang, only_last_component=Fal
         return author
 
     def get_overview_path(self, lang, dest_type='page'):
-        """A path handler for the list of all classifications."""
+        """Return a path for the list of all classifications."""
         return [self.site.config['AUTHOR_PATH'](lang)], 'always'
 
     def get_path(self, author, lang, dest_type='page'):
-        """A path handler for the given classification."""
+        """Return a path for the given classification."""
         if self.site.config['SLUG_AUTHOR_PATH']:
             slug = utils.slugify(author, lang)
         else:
diff --git a/nikola/plugins/task/categories.py b/nikola/plugins/task/categories.py
@@ -98,7 +98,7 @@ def get_classification_friendly_name(self, classification, lang, only_last_compo
         return classification[-1] if classification else ''
 
     def get_overview_path(self, lang, dest_type='page'):
-        """A path handler for the list of all classifications."""
+        """Return a path for the list of all classifications."""
         if self.site.config['CATEGORIES_INDEX_PATH'](lang):
             path = self.site.config['CATEGORIES_INDEX_PATH'](lang)
             if path.endswith('/index'):  # TODO: remove in v8
@@ -128,7 +128,7 @@ def slugify_category_name(self, path, lang):
         return result
 
     def get_path(self, classification, lang, dest_type='page'):
-        """A path handler for the given classification."""
+        """Return a path for the given classification."""
         return [_f for _f in [self.site.config['CATEGORY_PATH'](lang)] if _f] + self.slugify_category_name(classification, lang), 'auto'
 
     def extract_hierarchy(self, classification):
diff --git a/nikola/plugins/task/indexes.py b/nikola/plugins/task/indexes.py
@@ -91,7 +91,7 @@ def get_classification_friendly_name(self, classification, lang, only_last_compo
         return self.site.config["BLOG_TITLE"](lang)
 
     def get_path(self, classification, lang, dest_type='page'):
-        """A path handler for the given classification."""
+        """Return a path for the given classification."""
         if dest_type == 'rss':
             return [self.site.config['RSS_PATH'](lang)], True
         # 'page' (index) or 'feed' (Atom)
diff --git a/nikola/plugins/task/listings.py b/nikola/plugins/task/listings.py
@@ -260,7 +260,7 @@ def render_listing(in_name, out_name, input_folder, output_folder, folders=[], f
                     }, self.kw["filters"])
 
     def listing_source_path(self, name, lang):
-        """A link to the source code for a listing.
+        """Return a link to the source code for a listing.
 
         It will try to use the file name if it's not ambiguous, or the file path.
 
@@ -276,7 +276,7 @@ def listing_source_path(self, name, lang):
         return result
 
     def listing_path(self, namep, lang):
-        """A link to a listing.
+        """Return a link to a listing.
 
         It will try to use the file name if it's not ambiguous, or the file path.
 
diff --git a/nikola/plugins/task/page_index.py b/nikola/plugins/task/page_index.py
@@ -76,7 +76,7 @@ def get_classification_friendly_name(self, dirname, lang, only_last_component=Fa
         return dirname
 
     def get_path(self, hierarchy, lang, dest_type='page'):
-        """A path handler for the given classification."""
+        """Return a path for the given classification."""
         return hierarchy, 'always'
 
     def extract_hierarchy(self, dirname):
diff --git a/nikola/plugins/task/sections.py b/nikola/plugins/task/sections.py
@@ -97,7 +97,7 @@ def get_classification_friendly_name(self, section, lang, only_last_component=Fa
         return self._get_section_name(section, lang)
 
     def get_path(self, section, lang, dest_type='page'):
-        """A path handler for the given classification."""
+        """Return a path for the given classification."""
         result = [_f for _f in [section] if _f]
         if dest_type == 'rss':
             return result + ['rss.xml'], 'never'
diff --git a/nikola/plugins/task/tags.py b/nikola/plugins/task/tags.py
@@ -102,7 +102,7 @@ def slugify_tag_name(self, name, lang):
         return name
 
     def get_overview_path(self, lang, dest_type='page'):
-        """A path handler for the list of all classifications."""
+        """Return a path for the list of all classifications."""
         if self.site.config['TAGS_INDEX_PATH'](lang):
             path = self.site.config['TAGS_INDEX_PATH'](lang)
             if path.endswith('/index'):  # TODO: remove in v8
@@ -113,7 +113,7 @@ def get_overview_path(self, lang, dest_type='page'):
             return [_f for _f in [self.site.config['TAG_PATH'](lang)] if _f], 'always'
 
     def get_path(self, classification, lang, dest_type='page'):
-        """A path handler for the given classification."""
+        """Return a path for the given classification."""
         return [_f for _f in [
             self.site.config['TAG_PATH'](lang),
             self.slugify_tag_name(classification, lang)] if _f], 'auto'
diff --git a/nikola/post.py b/nikola/post.py
@@ -295,7 +295,7 @@ def _has_pretty_url(self, lang):
 
     @property
     def is_mathjax(self):
-        """True if this post has the mathjax tag in the current language or is a python notebook."""
+        """Return True if this post has the mathjax tag in the current language or is a python notebook."""
         if self.compiler.name == 'ipynb':
             return True
         lang = nikola.utils.LocaleBorg().current_lang
@@ -724,7 +724,7 @@ def text(self, lang=None, teaser_only=False, strip_html=False, show_read_more_li
 
     @property
     def reading_time(self):
-        """Reading time based on length of text."""
+        """Return reading time based on length of text."""
         if self._reading_time is None:
             text = self.text(strip_html=True)
             words_per_minute = 220
diff --git a/nikola/utils.py b/nikola/utils.py
@@ -529,7 +529,7 @@ class CustomEncoder(json.JSONEncoder):
     """Custom JSON encoder."""
 
     def default(self, obj):
-        """Default encoding handler."""
+        """Create default encoding handler."""
         try:
             return super(CustomEncoder, self).default(obj)
         except TypeError:
@@ -1671,7 +1671,7 @@ def adjust_name_for_index_link(name, i, displayed_i, lang, site, force_addition=
 
 
 def create_redirect(src, dst):
-    """"Create a redirection."""
+    """Create a redirection."""
     makedirs(os.path.dirname(src))
     with io.open(src, "w+", encoding="utf8") as fd:
         fd.write('<!DOCTYPE html>\n<head>\n<meta charset="utf-8">\n'
