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,47 @@
+/* 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;
+}
+
+/* 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,22 +3,38 @@
 
 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 2004 Manfred Stienstra (the original version)
+- Copyright 2007-2023 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 __future__ import annotations
+
 from .core import Markdown, markdown, markdownFromFile
 from .__meta__ import __version__, __version_info__  # noqa
 

markdown/__main__.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-2023 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 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-2023 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, #)
@@ -26,11 +24,15 @@
 #     (1, 2, 0, 'beta', 2) => "1.2b2"
 #     (1, 2, 0, 'rc', 4) => "1.2rc4"
 #     (1, 2, 0, 'final', 0) => "1.2"
+
+from __future__ import annotations
+
+
 __version_info__ = (3, 4, 4, 'final', 0)
 
 
 def _get_version(version_info):
-    " Returns a PEP 440-compliant version number from version_info. "
+    " Returns a PEP 440-compliant version number from `version_info`. "
     assert len(version_info) == 5
     assert version_info[3] in ('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-2023 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,30 +66,42 @@ 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):
-        """ Parse a markdown document into an ElementTree.
+    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
-        Element) is created and the root element is passed to the parser
-        as the parent. The ElementTree object is returned.
+        Given a list of lines, an `ElementTree` object (not just a parent
+        `Element`) is created and the root element is passed to the parser
+        as the parent. The `ElementTree` object is returned.
 
         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):
-        """ Parse a chunk of markdown text and attach to given `etree` node.
+    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
         blocks which will be split on blank lines, it could contain only one
@@ -95,11 +111,15 @@ 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):
-        """ Process blocks of markdown text and attach to given `etree` node.
+    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
         until there are no blocks left. While an extension could potentially
@@ -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: