docs: fix docstrings formatting

pyrevitlib/pyrevit/coreutils/markdown/extensions/abbr.py

@@ -36,10 +36,10 @@ class AbbrPreprocessor(Preprocessor):
     """Abbreviation Preprocessor - parse text for abbr references."""
 
     def run(self, lines):
-        '''Find and remove all Abbreviation references from the text.
-        Each reference is set as a new AbbrPattern in the markdown instance.
+        """Find and remove all Abbreviation references from the text.
 
-        '''
+        Each reference is set as a new AbbrPattern in the markdown instance.
+        """
         new_text = []
         for line in lines:
             m = ABBR_REF_RE.match(line)
@@ -53,14 +53,14 @@ def run(self, lines):
         return new_text
 
     def _generate_pattern(self, text):
-        '''Given a string, returns an regex pattern to match that string.
+        """Given a string, returns an regex pattern to match that string.
 
         'HTML' -> r'(?P<abbr>[H][T][M][L])'
 
         Note: we force each char as a literal match (in brackets) as we don't
         know what they will be beforehand.
 
-        '''
+        """
         chars = list(text)
         for i in range(len(chars)):
             chars[i] = r'[%s]' % chars[i]

pyrevitlib/pyrevit/coreutils/markdown/extensions/admonition.py

@@ -1,5 +1,4 @@
-"""Admonition extension for Python-Markdown
-========================================.
+"""Admonition extension for Python-Markdown.
 
 Adds rST-style admonitions. Inspired by [rST][] feature with the same name.
 
@@ -13,7 +12,6 @@
 All changes Copyright The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import

pyrevitlib/pyrevit/coreutils/markdown/extensions/attr_list.py

@@ -1,5 +1,4 @@
-"""Attribute List Extension for Python-Markdown
-============================================.
+"""Attribute List Extension for Python-Markdown.
 
 Adds attribute list syntax. Inspired by
 [maruku](http://maruku.rubyforge.org/proposal.html#attribute_lists)'s
@@ -13,7 +12,6 @@
 All changes Copyright 2011-2014 The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import
@@ -160,6 +158,7 @@ def assign_attrs(self, elem, attrs):
 
     def sanitize_name(self, name):
         """Sanitize name as 'an XML Name, minus the ":"'.
+        
         See http://www.w3.org/TR/REC-xml-names/#NT-NCName.
         """
         return self.NAME_RE.sub('_', name)

pyrevitlib/pyrevit/coreutils/markdown/extensions/codehilite.py

@@ -1,5 +1,4 @@
-"""CodeHilite Extension for Python-Markdown
-========================================.
+"""CodeHilite Extension for Python-Markdown.
 
 Adds code/syntax highlighting to standard Python-Markdown code blocks.
 
@@ -11,7 +10,6 @@
 All changes Copyright 2008-2014 The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import
@@ -86,13 +84,15 @@ def __init__(self, src=None, linenums=None, guess_lang=True,
         self.use_pygments = use_pygments
 
     def hilite(self):
-        """Pass code to the [Pygments](http://pygments.pocoo.org/) highliter with
+        """Highlites the code.
+
+        Pass code to the [Pygments](http://pygments.pocoo.org/) highliter with
         optional line numbers. The output should then be styled with css to
         your liking. No styles are applied by default - only styling hooks
         (i.e.: <span class="k">).
 
-        returns : A string of html.
-
+        Returns:
+            (str): html text of the highlighted code.
         """
         self.src = self.src.strip('\n')
 
@@ -135,7 +135,9 @@ def hilite(self):
                    (self.css_class, class_str, txt)
 
     def _parseHeader(self):
-        """Determines language of a code block from shebang line and whether said
+        """Parse the code block header.
+
+        Determines language of a code block from shebang line and whether said
         line should be removed or left in place. If the sheband line contains a
         path (even a single /) then it is assumed to be a real shebang line and
         left alone. However, if no path is given (e.i.: #!python or :::python)

pyrevitlib/pyrevit/coreutils/markdown/extensions/def_list.py

@@ -1,5 +1,4 @@
-"""Definition List Extension for Python-Markdown
-=============================================.
+"""Definition List Extension for Python-Markdown.
 
 Adds parsing of Definition Lists to Python-Markdown.
 
@@ -11,7 +10,6 @@
 All changes Copyright 2008-2014 The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import

pyrevitlib/pyrevit/coreutils/markdown/extensions/extra.py

@@ -1,5 +1,4 @@
-"""Python-Markdown Extra Extension
-===============================.
+"""Python-Markdown Extra Extension.
 
 A compilation of various Python-Markdown extensions that imitates
 [PHP Markdown Extra](http://michelf.com/projects/php-markdown/extra/).
@@ -25,7 +24,6 @@
 Copyright The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import

pyrevitlib/pyrevit/coreutils/markdown/extensions/fenced_code.py

@@ -1,5 +1,4 @@
-"""Fenced Code Extension for Python Markdown
-=========================================.
+"""Fenced Code Extension for Python Markdown.
 
 This extension adds Fenced Code Blocks to Python-Markdown.
 

pyrevitlib/pyrevit/coreutils/markdown/extensions/footnotes.py

@@ -1,5 +1,4 @@
-"""Footnotes Extension for Python-Markdown
-=======================================.
+"""Footnotes Extension for Python-Markdown.
 
 Adds footnote handling to Python-Markdown.
 
@@ -9,7 +8,6 @@
 Copyright The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import

pyrevitlib/pyrevit/coreutils/markdown/extensions/headerid.py

@@ -1,5 +1,4 @@
-"""HeaderID Extension for Python-Markdown
-======================================.
+"""HeaderID Extension for Python-Markdown.
 
 Auto-generate id attributes for HTML headers.
 
@@ -11,7 +10,6 @@
 All changes Copyright 2011-2014 The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import

pyrevitlib/pyrevit/coreutils/markdown/extensions/meta.py

@@ -1,5 +1,4 @@
-"""Meta Data Extension for Python-Markdown
-=======================================.
+"""Meta Data Extension for Python-Markdown.
 
 This extension adds Meta Data handling to markdown.
 
@@ -11,7 +10,6 @@
 All changes Copyright 2008-2014 The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import

pyrevitlib/pyrevit/coreutils/markdown/extensions/nl2br.py

@@ -1,5 +1,4 @@
-"""NL2BR Extension
-===============.
+"""NL2BR Extension.
 
 A Python-Markdown extension to treat newlines as hard breaks; like
 GitHub-flavored Markdown does.
@@ -12,7 +11,6 @@
 All changes Copyright 2011-2014 The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import

pyrevitlib/pyrevit/coreutils/markdown/extensions/sane_lists.py

@@ -1,5 +1,4 @@
-"""Sane List Extension for Python-Markdown
-=======================================.
+"""Sane List Extension for Python-Markdown.
 
 Modify the behavior of Lists in Python-Markdown to act in a sane manor.
 
@@ -11,7 +10,6 @@
 All changes Copyright 2011-2014 The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import

pyrevitlib/pyrevit/coreutils/markdown/extensions/toc.py

@@ -1,5 +1,4 @@
-"""Table of Contents Extension for Python-Markdown
-===============================================.
+"""Table of Contents Extension for Python-Markdown.
 
 See <https://pythonhosted.org/Markdown/extensions/toc.html>
 for documentation.
@@ -9,7 +8,6 @@
 All changes Copyright 2008-2014 The Python Markdown Project
 
 License: [BSD](http://www.opensource.org/licenses/bsd-license.php)
-
 """
 
 from __future__ import absolute_import
@@ -61,14 +59,16 @@ def _html_sub(m):
 
 def nest_toc_tokens(toc_list):
     """Given an unsorted list with errors and skips, return a nested one.
-    [{'level': 1}, {'level': 2}]
-    =>
-    [{'level': 1, 'children': [{'level': 2, 'children': []}]}].
-
-    A wrong list is also converted:
-    [{'level': 2}, {'level': 1}]
-    =>
-    [{'level': 2, 'children': []}, {'level': 1, 'children': []}]
+
+    Examples:
+        [{'level': 1}, {'level': 2}]
+        =>
+        [{'level': 1, 'children': [{'level': 2, 'children': []}]}].
+
+        A wrong list is also converted:
+        [{'level': 2}, {'level': 1}]
+        =>
+        [{'level': 2, 'children': []}, {'level': 1, 'children': []}]
     """
     ordered_list = []
     if len(toc_list):
@@ -138,13 +138,13 @@ def __init__(self, md, config):
         self.header_rgx = re.compile("[Hh][123456]")
 
     def iterparent(self, root):
-        '''Iterator wrapper to get parent and child all at once.'''
+        """Iterator wrapper to get parent and child all at once."""
         for parent in root.iter():
             for child in parent:
                 yield parent, child
 
     def replace_marker(self, root, elem):
-        '''Replace marker with elem.'''
+        """Replace marker with elem."""
         for (p, c) in self.iterparent(root):
             text = ''.join(c.itertext()).strip()
             if not text:
@@ -164,7 +164,7 @@ def replace_marker(self, root, elem):
                         break
 
     def set_level(self, elem):
-        '''Adjust header level according to base level.'''
+        """Adjust header level according to base level."""
         level = int(elem.tag[-1]) + self.base_level
         if level > 6:
             level = 6

pyrevitlib/pyrevit/coreutils/markdown/inlinepatterns.py

@@ -1,5 +1,4 @@
-"""INLINE PATTERNS
-=============================================================================.
+"""INLINE PATTERNS.
 
 Inline patterns such as *emphasis* are handled by means of auxiliary
 objects, one per pattern.  Pattern objects must be instances of classes
@@ -196,6 +195,7 @@ def __init__(self, pattern, markdown_instance=None):
 
         Args:
             pattern (str): A regular expression that matches a pattern
+            markdown_instance (markdown.Markdown): Instance of Markdown
         """
         self.pattern = pattern
         self.compiled_re = re.compile("^(.*?)%s(.*)$" % pattern,
@@ -232,7 +232,7 @@ def unescape(self, text):
             return text
 
         def itertext(el):  # pragma: no cover
-            'Reimplement Element.itertext for older python versions.'
+            """Reimplement Element.itertext for older python versions."""
             tag = el.tag
             if not isinstance(tag, util.string_type) and tag is not None:
                 return
@@ -274,10 +274,7 @@ def handleMatch(self, m):
 
 
 class SimpleTagPattern(Pattern):
-    """Return element of type `tag` with a text attribute of group(3)
-    of a Pattern.
-
-    """
+    """Return a `tag` element with a text attribute of group(3) of a Pattern."""
     def __init__(self, pattern, tag):
         Pattern.__init__(self, pattern)
         self.tag = tag

pyrevitlib/pyrevit/coreutils/markdown/postprocessors.py

@@ -1,10 +1,8 @@
-"""POST-PROCESSORS
-=============================================================================.
+"""POST-PROCESSORS.
 
 Markdown also allows post-processors, which are similar to preprocessors in
 that they need to implement a "run" method. However, they are run after core
 processing.
-
 """
 
 from __future__ import absolute_import
@@ -37,10 +35,11 @@ class Postprocessor(util.Processor):
     """
 
     def run(self, text):
-        """Subclasses of Postprocessor should implement a `run` method, which
+        """Main postprocessor method.
+
+        Subclasses of Postprocessor should implement a `run` method, which
         takes the html document as a single text string and returns a
         (possibly modified) string.
-
         """
         pass  # pragma: no cover
 

pyrevitlib/pyrevit/coreutils/markdown/preprocessors.py

@@ -1,5 +1,4 @@
-"""PRE-PROCESSORS
-=============================================================================.
+"""PRE-PROCESSORS.
 
 Preprocessors work on source text before we start doing anything too
 complicated.
@@ -32,10 +31,11 @@ class Preprocessor(util.Processor):
     either the same pointer or a pointer to a new list.
 
     Preprocessors must extend markdown.Preprocessor.
-
     """
     def run(self, lines):
-        """Each subclass of Preprocessor should override the `run` method, which
+        """Main preprocessor task.
+
+        Each subclass of Preprocessor should override the `run` method, which
         takes the document as a list of strings split by newlines and returns
         the (possibly modified) list of lines.
 
@@ -143,7 +143,9 @@ def _is_oneliner(self, tag):
         return (tag in ['hr', 'hr/'])
 
     def _stringindex_to_listindex(self, stringindex, items):
-        """Same effect as concatenating the strings in items,
+        """Return the index of the item matching the cumulative string index.
+
+        Same effect as concatenating the strings in items,
         finding the character to which stringindex refers in that string,
         and returning the index of the item in which that character resides.
         """