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 @@
 
  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 @@
 
  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 @@
  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 @@
  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
 ===========================================================================