Add API docs

.gitignore

@@ -64,6 +64,7 @@ target/
 .python-version
 
 # virtualenv
+.venv/
 venv/
 ENV/
 

docs/extensions/api.md

@@ -845,7 +845,7 @@ assert someitem in registry
 
 :   Add an item to the registry with the given name and priority.
 
-    Parameters:
+    Arguments:
 
     * `item`: The item being registered.
     * `name`: A string used to reference the item.

docs/mkdocstrings.css

@@ -0,0 +1,52 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+
+  height: 1em;
+  width: 1em;
+  background-color: #005b81;
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: #e32e00;
+}
+
+/* Cancel codehilite background in headings. */
+.doc-heading .codehilite {
+  background: unset;
+}
+
+/* Customize symbol names. */
+code.doc-symbol-attribute::after {
+  content: "Attr";
+}
+
+code.doc-symbol-function::after {
+  content: "Func";
+}
+
+code.doc-symbol-method::after {
+  content: "Method";
+}
+
+code.doc-symbol-class::after {
+  content: "Class";
+}
+
+code.doc-symbol-module::after {
+  content: "Module";
+}

markdown/__init__.py

@@ -3,20 +3,34 @@
 
 A Python implementation of John Gruber's Markdown.
 
-Documentation: https://python-markdown.github.io/
-GitHub: https://github.com/Python-Markdown/markdown/
-PyPI: https://pypi.org/project/Markdown/
+- Documentation: https://python-markdown.github.io/
+- GitHub: https://github.com/Python-Markdown/markdown/
+- PyPI: https://pypi.org/project/Markdown/
 
 Started by Manfred Stienstra (http://www.dwerg.net/).
 Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
 Currently maintained by Waylan Limberg (https://github.com/waylan),
 Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
 
-Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
-Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
+Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)  
+Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)  
 Copyright 2004 Manfred Stienstra (the original version)
 
 License: BSD (see LICENSE.md for details).
+
+Modules:
+    core: Core functionality.
+    preprocessors: Pre-processors.
+    blockparser: Core Markdown block parser.
+    blockprocessors: Block processors.
+    treeprocessors: Tree processors.
+    inlinepatterns: Inline patterns.
+    postprocessors: Post-processors.
+    serializers: Serializers.
+    util: Utility functions.
+    htmlparser: HTML parser.
+    test_tools: Testing utilities.
+    extensions: Markdown extensions.
 """
 
 from .core import Markdown, markdown, markdownFromFile

markdown/__main__.py

@@ -1,23 +1,21 @@
-"""
-Python Markdown
+# Python Markdown
 
-A Python implementation of John Gruber's Markdown.
+# A Python implementation of John Gruber's Markdown.
 
-Documentation: https://python-markdown.github.io/
-GitHub: https://github.com/Python-Markdown/markdown/
-PyPI: https://pypi.org/project/Markdown/
+# Documentation: https://python-markdown.github.io/
+# GitHub: https://github.com/Python-Markdown/markdown/
+# PyPI: https://pypi.org/project/Markdown/
 
-Started by Manfred Stienstra (http://www.dwerg.net/).
-Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
-Currently maintained by Waylan Limberg (https://github.com/waylan),
-Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
+# Started by Manfred Stienstra (http://www.dwerg.net/).
+# Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
+# Currently maintained by Waylan Limberg (https://github.com/waylan),
+# Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
 
-Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
-Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
-Copyright 2004 Manfred Stienstra (the original version)
+# Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
+# Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
+# Copyright 2004 Manfred Stienstra (the original version)
 
-License: BSD (see LICENSE.md for details).
-"""
+# License: BSD (see LICENSE.md for details).
 
 import sys
 import optparse

markdown/__meta__.py

@@ -1,23 +1,21 @@
-"""
-Python Markdown
+# Python Markdown
 
-A Python implementation of John Gruber's Markdown.
+# A Python implementation of John Gruber's Markdown.
 
-Documentation: https://python-markdown.github.io/
-GitHub: https://github.com/Python-Markdown/markdown/
-PyPI: https://pypi.org/project/Markdown/
+# Documentation: https://python-markdown.github.io/
+# GitHub: https://github.com/Python-Markdown/markdown/
+# PyPI: https://pypi.org/project/Markdown/
 
-Started by Manfred Stienstra (http://www.dwerg.net/).
-Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
-Currently maintained by Waylan Limberg (https://github.com/waylan),
-Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
+# Started by Manfred Stienstra (http://www.dwerg.net/).
+# Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
+# Currently maintained by Waylan Limberg (https://github.com/waylan),
+# Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
 
-Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
-Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
-Copyright 2004 Manfred Stienstra (the original version)
+# Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
+# Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
+# Copyright 2004 Manfred Stienstra (the original version)
 
-License: BSD (see LICENSE.md for details).
-"""
+# License: BSD (see LICENSE.md for details).
 
 # __version_info__ format:
 #     (major, minor, patch, dev/alpha/beta/rc/final, #)

markdown/blockparser.py

@@ -1,27 +1,31 @@
-"""
-Python Markdown
+# Python Markdown
 
-A Python implementation of John Gruber's Markdown.
+# A Python implementation of John Gruber's Markdown.
 
-Documentation: https://python-markdown.github.io/
-GitHub: https://github.com/Python-Markdown/markdown/
-PyPI: https://pypi.org/project/Markdown/
+# Documentation: https://python-markdown.github.io/
+# GitHub: https://github.com/Python-Markdown/markdown/
+# PyPI: https://pypi.org/project/Markdown/
 
-Started by Manfred Stienstra (http://www.dwerg.net/).
-Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
-Currently maintained by Waylan Limberg (https://github.com/waylan),
-Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
+# Started by Manfred Stienstra (http://www.dwerg.net/).
+# Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
+# Currently maintained by Waylan Limberg (https://github.com/waylan),
+# Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
 
-Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
-Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
-Copyright 2004 Manfred Stienstra (the original version)
+# Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
+# Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
+# Copyright 2004 Manfred Stienstra (the original version)
 
-License: BSD (see LICENSE.md for details).
-"""
+# License: BSD (see LICENSE.md for details).
+
+from __future__ import annotations
 
 import xml.etree.ElementTree as etree
+from typing import TYPE_CHECKING, Sequence
 from . import util
 
+if TYPE_CHECKING:
+    from markdown import Markdown
+
 
 class State(list):
     """ Track the current and nested state of the parser.
@@ -62,14 +66,21 @@ class BlockParser:
 
     A wrapper class that stitches the various `BlockProcessors` together,
     looping through them and creating an `ElementTree` object.
+
     """
 
-    def __init__(self, md):
+    def __init__(self, md: Markdown):
+        """ Initialize the block parser.
+
+        Arguments:
+            md: A Markdown instance.
+
+        """
         self.blockprocessors = util.Registry()
         self.state = State()
         self.md = md
 
-    def parseDocument(self, lines):
+    def parseDocument(self, lines: Sequence[str]) -> etree.ElementTree:
         """ Parse a markdown document into an ElementTree.
 
         Given a list of lines, an ElementTree object (not just a parent
@@ -78,13 +89,18 @@ def parseDocument(self, lines):
 
         This should only be called on an entire document, not pieces.
 
+        Arguments:
+            lines: A list of lines (strings).
+
+        Returns:
+            An element tree.
         """
         # Create an `ElementTree` from the lines
         self.root = etree.Element(self.md.doc_tag)
         self.parseChunk(self.root, '\n'.join(lines))
         return etree.ElementTree(self.root)
 
-    def parseChunk(self, parent, text):
+    def parseChunk(self, parent: etree.Element, text: str):
         """ Parse a chunk of markdown text and attach to given `etree` node.
 
         While the `text` argument is generally assumed to contain multiple
@@ -95,10 +111,14 @@ def parseChunk(self, parent, text):
         The `parent` `etree` Element passed in is altered in place.
         Nothing is returned.
 
+        Arguments:
+            parent: The parent element.
+            text: The text to parse.
+
         """
         self.parseBlocks(parent, text.split('\n\n'))
 
-    def parseBlocks(self, parent, blocks):
+    def parseBlocks(self, parent: etree.Element, blocks: Sequence[str]):
         """ Process blocks of markdown text and attach to given `etree` node.
 
         Given a list of `blocks`, each `blockprocessor` is stepped through
@@ -110,6 +130,10 @@ def parseBlocks(self, parent, blocks):
         additional `BlockProcessors` which call this method to recursively
         parse a nested block.
 
+        Arguments:
+            parent: The parent element.
+            blocks: The blocks of text to parse.
+
         """
         while blocks:
             for processor in self.blockprocessors:

markdown/blockprocessors.py

@@ -1,23 +1,23 @@
-"""
-Python Markdown
+# Python Markdown
 
-A Python implementation of John Gruber's Markdown.
+# A Python implementation of John Gruber's Markdown.
 
-Documentation: https://python-markdown.github.io/
-GitHub: https://github.com/Python-Markdown/markdown/
-PyPI: https://pypi.org/project/Markdown/
+# Documentation: https://python-markdown.github.io/
+# GitHub: https://github.com/Python-Markdown/markdown/
+# PyPI: https://pypi.org/project/Markdown/
 
-Started by Manfred Stienstra (http://www.dwerg.net/).
-Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
-Currently maintained by Waylan Limberg (https://github.com/waylan),
-Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
+# Started by Manfred Stienstra (http://www.dwerg.net/).
+# Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
+# Currently maintained by Waylan Limberg (https://github.com/waylan),
+# Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
 
-Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
-Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
-Copyright 2004 Manfred Stienstra (the original version)
+# Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
+# Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
+# Copyright 2004 Manfred Stienstra (the original version)
 
-License: BSD (see LICENSE.md for details).
+# License: BSD (see LICENSE.md for details).
 
+"""
 CORE MARKDOWN BLOCKPARSER
 ===========================================================================