From 16b98682e6ee2771ae2df748e50146684115fcb3 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Mon, 10 Mar 2008 03:56:33 +0000 Subject: Edited existing docstrings to more closely conform to PEP 257 and to contain markdown formatting. Still a lot of documentation improvments to go. --- markdown.py | 286 ++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 180 insertions(+), 106 deletions(-) diff --git a/markdown.py b/markdown.py index 3dc8f00..b63c9fe 100644 --- a/markdown.py +++ b/markdown.py @@ -1,9 +1,4 @@ -#!/usr/bin/env python - -version = "1.7" -version_info = (1,7,0,"rc-2") -__revision__ = "$Rev$" - +#!/usr/bin/python """ Python-Markdown =============== @@ -23,13 +18,20 @@ Started by [Manfred Stienstra](http://www.dwerg.net/). Continued and maintained by [Yuri Takhteyev](http://www.freewisdom.org) and [Waylan Limberg](http://achinghead.com/). -Contact: yuri [at] freewisdom.org - waylan [at] gmail.com +Contact: -License: GPL 2 (http://www.gnu.org/copyleft/gpl.html) or BSD +* +* + +License: [GPL 2](http://www.gnu.org/copyleft/gpl.html) or BSD """ +version = "1.7" +version_info = (1,7,0,"rc-2") +__revision__ = "$Rev$" + + import re, sys, codecs @@ -419,6 +421,7 @@ class TextPreprocessor: either the same pointer or a pointer to a new string. TextPreprocessors must extend markdown.TextPreprocessor. + ''' def run(self, text): @@ -434,6 +437,7 @@ class Preprocessor: either the same pointer or a pointer to a new list. Preprocessors must extend markdown.Preprocessor. + ''' def run(self, lines): @@ -541,8 +545,8 @@ HTML_BLOCK_PREPROCESSOR = HtmlBlockPreprocessor() class HeaderPreprocessor(Preprocessor): """ - Replaces underlined headers with hashed headers to avoid - the nead for lookahead later. + Replaces underlined headers with hashed headers to avoid + the nead for lookahead later. """ def run (self, lines): @@ -935,6 +939,7 @@ class Postprocessor: There are currently no standard post-processors, but the footnote extension uses one. + ''' def run(self, dom): @@ -950,6 +955,7 @@ class TextPostprocessor: text string, modifies it as necessary and returns a text string. TextPostprocessors must extend markdown.TextPostprocessor. + ''' def run(self, text): @@ -993,22 +999,29 @@ RAWHTMLTEXTPOSTPROCESSOR = RawHtmlTextPostprocessor() """ class HtmlStash: - """This class is used for stashing HTML objects that we extract - in the beginning and replace with place-holders.""" + """ + This class is used for stashing HTML objects that we extract + in the beginning and replace with place-holders. + """ def __init__ (self): self.html_counter = 0 # for counting inline html segments self.rawHtmlBlocks=[] def store(self, html, safe=False): - """Saves an HTML segment for later reinsertion. Returns a - placeholder string that needs to be inserted into the - document. - - @param html: an html segment - @param safe: label an html segment as safe for safemode - @param inline: label a segmant as inline html - @returns : a placeholder string """ + """ + Saves an HTML segment for later reinsertion. Returns a + placeholder string that needs to be inserted into the + document. + + Keyword arguments: + + * html: an html segment + * safe: label an html segment as safe for safemode + + Returns : a placeholder string + + """ self.rawHtmlBlocks.append((html, safe)) placeholder = HTML_PLACEHOLDER % self.html_counter self.html_counter += 1 @@ -1019,16 +1032,22 @@ class BlockGuru: def _findHead(self, lines, fn, allowBlank=0): - """Functional magic to help determine boundaries of indented - blocks. + """ + Functional magic to help determine boundaries of indented + blocks. - @param lines: an array of strings - @param fn: a function that returns a substring of a string - if the string matches the necessary criteria - @param allowBlank: specifies whether it's ok to have blank - lines between matching functions - @returns: a list of post processes items and the unused - remainder of the original list""" + Keyword arguments: + + * lines: an array of strings + * fn: a function that returns a substring of a string + if the string matches the necessary criteria + * allowBlank: specifies whether it's ok to have blank + lines between matching functions + + Returns: a list of post processes items and the unused + remainder of the original list + + """ items = [] item = -1 @@ -1116,8 +1135,9 @@ inline patterns or a combination of the three. """ class CorePatterns: - """This class is scheduled for removal as part of a refactoring - effort.""" + """ + This class is scheduled for removal as part of a refactoring effort. + """ patterns = { 'header': r'(#*)([^#]*)(#*)', # # A title @@ -1146,24 +1166,29 @@ RE = CorePatterns() class Markdown: - """ Markdown formatter class for creating an html document from - Markdown text """ + """ + Markdown formatter class for creating an html document from Markdown text. + """ def __init__(self, source=None, # depreciated extensions=[], extension_configs={}, safe_mode = False): - """Creates a new Markdown instance. + """ + Creates a new Markdown instance. - @param source: The text in Markdown format. Depreciated! - @param extensions: A list of extensions. - If they are of type string, the module - mdx_name.py will be loaded - If they are a subclass of markdown.Extension, - they will be used as-is - @param extension-configs: Configuration setting for extensions. - @param safe_mode: Disallow raw html. """ + Keyword arguments: + + * source: The text in Markdown format. Depreciated! + * extensions: A list of extensions. + If they are of type string, the module mdx_name.py will be loaded. + If they are a subclass of markdown.Extension, they will be used + as-is. + * extension-configs: Configuration setting for extensions. + * safe_mode: Disallow raw html. + + """ self.source = source if source is not None: @@ -1224,13 +1249,16 @@ class Markdown: def registerExtensions(self, extensions, configs): - """ Register extensions with this instance of Markdown. + """ + Register extensions with this instance of Markdown. - @param extensions A list of extensions, which can either - be strings or objects. See the docstring - on Markdown. - @param configs A dictionary mapping module names to config - options. """ + Keyword aurguments: + + * extensions: A list of extensions, which can either + be strings or objects. See the docstring on Markdown. + * configs: A dictionary mapping module names to config options. + + """ for ext in extensions: if isinstance(ext, basestring): @@ -1250,8 +1278,9 @@ class Markdown: self.registeredExtensions.append(extension) def reset(self): - """Resets all state variables so that we can start - with a new text.""" + """ + Resets all state variables so that we can start with a new text. + """ self.references={} self.htmlStash = HtmlStash() @@ -1272,7 +1301,9 @@ class Markdown: def _transform(self): """Transforms the Markdown text into a XHTML body document - @returns: A NanoDom Document """ + Returns: A NanoDom Document + + """ # Setup the document @@ -1317,18 +1348,22 @@ class Markdown: def _processSection(self, parent_elem, lines, inList = 0, looseList = 0): + """ + Process a section of a source document, looking for high + level structural elements like lists, block quotes, code + segments, html blocks, etc. Some those then get stripped + of their high level markup (e.g. get unindented) and the + lower-level markup is processed recursively. - """Process a section of a source document, looking for high - level structural elements like lists, block quotes, code - segments, html blocks, etc. Some those then get stripped - of their high level markup (e.g. get unindented) and the - lower-level markup is processed recursively. - - @param parent_elem: A NanoDom element to which the content - will be added - @param lines: a list of lines - @param inList: a level - @returns: None""" + Keyword arguments: + + * parent_elem: A NanoDom element to which the content will be added. + * lines: a list of lines + * inList: a level + + Returns: None + + """ # Loop through lines until none left. while lines: @@ -1430,14 +1465,20 @@ class Markdown: def _processList(self, parent_elem, lines, inList, listexpr, tag): - """Given a list of document lines starting with a list item, - finds the end of the list, breaks it up, and recursively - processes each list item and the remainder of the text file. + """ + Given a list of document lines starting with a list item, + finds the end of the list, breaks it up, and recursively + processes each list item and the remainder of the text file. - @param parent_elem: A dom element to which the content will be added - @param lines: a list of lines - @param inList: a level - @returns: None""" + Keyword arguments: + + * parent_elem: A dom element to which the content will be added + * lines: a list of lines + * inList: a level + + Returns: None + + """ ul = self.doc.createElement(tag) # ul might actually be '
    ' parent_elem.appendChild(ul) @@ -1515,10 +1556,12 @@ class Markdown: def _linesUntil(self, lines, condition): - """ A utility function to break a list of lines upon the - first line that satisfied a condition. The condition - argument should be a predicate function. - """ + """ + A utility function to break a list of lines upon the + first line that satisfied a condition. The condition + argument should be a predicate function. + + """ i = -1 for line in lines: @@ -1529,15 +1572,21 @@ class Markdown: return lines[:i], lines[i:] def _processQuote(self, parent_elem, lines, inList): - """Given a list of document lines starting with a quote finds - the end of the quote, unindents it and recursively - processes the body of the quote and the remainder of the - text file. + """ + Given a list of document lines starting with a quote finds + the end of the quote, unindents it and recursively + processes the body of the quote and the remainder of the + text file. - @param parent_elem: DOM element to which the content will be added - @param lines: a list of lines - @param inList: a level - @returns: None """ + Keyword arguments: + + * parent_elem: DOM element to which the content will be added + * lines: a list of lines + * inList: a level + + Returns: None + + """ dequoted = [] i = 0 @@ -1568,15 +1617,21 @@ class Markdown: def _processCodeBlock(self, parent_elem, lines, inList): - """Given a list of document lines starting with a code block - finds the end of the block, puts it into the dom verbatim - wrapped in ("
    ") and recursively processes the
-           the remainder of the text file.
+        """
+        Given a list of document lines starting with a code block
+        finds the end of the block, puts it into the dom verbatim
+        wrapped in ("
    ") and recursively processes the
+        the remainder of the text file.
 
-           @param parent_elem: DOM element to which the content will be added
-           @param lines: a list of lines
-           @param inList: a level
-           @returns: None"""
+        Keyword arguments:
+        
+        * parent_elem: DOM element to which the content will be added
+        * lines: a list of lines
+        * inList: a level
+        
+        Returns: None
+        
+        """
 
         detabbed, theRest = self.blockGuru.detectTabbed(lines)
 
@@ -1592,15 +1647,21 @@ class Markdown:
 
 
     def _handleInline (self, line, patternIndex=0):
-        """Transform a Markdown line with inline elements to an XHTML
+        """
+        Transform a Markdown line with inline elements to an XHTML
         fragment.
 
         This function uses auxiliary objects called inline patterns.
         See notes on inline patterns above.
 
-        @param line: A line of Markdown text
-        @param patternIndex: The index of the inlinePattern to start with
-        @return: A list of NanoDom nodes """
+        Keyword arguments:
+        
+        * line: A line of Markdown text
+        * patternIndex: The index of the inlinePattern to start with
+        
+        Return: A list of NanoDom nodes 
+        
+        """
 
 
         parts = [line]
@@ -1637,15 +1698,18 @@ class Markdown:
 
     def _applyPattern(self, line, pattern, patternIndex):
 
-        """ Given a pattern name, this function checks if the line
+        """ 
+        Given a pattern name, this function checks if the line
         fits the pattern, creates the necessary elements, and returns
         back a list consisting of NanoDom elements and/or strings.
         
-        @param line: the text to be processed
-        @param pattern: the pattern to be checked
+        Keyword arguments:
+        
+        * line: the text to be processed
+        * pattern: the pattern to be checked
 
-        @returns: the appropriate newly created NanoDom element if the
-                  pattern matches, None otherwise.
+        Returns: The appropriate newly created NanoDom element if the
+           pattern matches, None otherwise.
         """
 
         # match the line to pattern's pre-compiled reg exp.
@@ -1704,10 +1768,17 @@ class Markdown:
         else:
             return None
 
-    def convert (self, source = None):
-        """Return the document in XHTML format.
+    def convert (self, source=None):
+        """
+        Return the document in XHTML format.
+
+        Keyword arguments:
+        
+        * source: An ascii or unicode string of Markdown formated text.
 
-        @returns: A serialized XHTML body."""
+        Returns: A serialized XHTML body.
+
+        """
 
         if source is not None: #Allow blank string
             self.source = source
@@ -1825,9 +1896,12 @@ class Extension:
 
 
 def load_extension(ext_name, configs = []):
-    """ Load extention by name, then return the module.
-        The name may contain arguments.
-        Print an error message and exit on failure. """
+    """ 
+    Load extention by name, then return the module.
+    The name may contain arguments.
+    Print an error message and exit on failure. 
+    
+    """
 
     # I am making the assumption that the order of config options
     # does not matter.
@@ -1892,7 +1966,7 @@ def parse_options():
                       help="print info messages")
     parser.add_option("-s", "--safe", dest="safe", default=False,
                       metavar="SAFE_MODE",
-                      help="same mode ('replace', 'remove' or 'escape'  user's HTML tag)")
+                      help="safe mode ('replace', 'remove' or 'escape'  user's HTML tag)")
     
     parser.add_option("--noisy",
                       action="store_const", const=DEBUG, dest="verbose",
-- 
cgit v1.2.3