New Upstream Release - mkautodoc
Ready changes
Summary
Merged new upstream version: 0.2.0 (was: 0.1.0).
Resulting package
Built on 2022-12-20T05:39 (took 2m21s)
The resulting binary packages can be installed (if you have the apt repository enabled) by running one of:
apt install -t fresh-releases python3-mkautodoc
Lintian Result
Diff
diff --git a/README.md b/README.md
index 7870242..3a5d0ed 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,8 @@ Python API documention for MkDocs.
This markdown extension adds `autodoc` style support, for use with MkDocs.
+
+
## Usage
#### 1. Include the extension in you `mkdocs.yml` config file:
@@ -34,6 +36,31 @@ you may need to use `pip install -e .` or modify `PYTHONPATH` in your docs build
:members:
```
+#### 4. Optionally, add styling for the API docs
+
+Update your `mkdocs.yml` to include some custom CSS.
+
+```yaml
+[...]
+extra_css:
+ - css/custom.css
+```
+
+Then add a `css/custom.css` file to your documentation.
+
+```css
+div.autodoc-docstring {
+ padding-left: 20px;
+ margin-bottom: 30px;
+ border-left: 5px solid rgba(230, 230, 230);
+}
+
+div.autodoc-members {
+ padding-left: 20px;
+ margin-bottom: 15px;
+}
+```
+
## Notes
#### The :docstring: declaration.
diff --git a/debian/changelog b/debian/changelog
index eb96ef0..ee802ac 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,10 +1,12 @@
-mkautodoc (0.1.0-5) UNRELEASED; urgency=medium
+mkautodoc (0.2.0-1) UNRELEASED; urgency=medium
* Trim trailing whitespace.
* Set upstream metadata fields: Bug-Database, Bug-Submit, Repository-Browse.
* Update standards version to 4.6.1, no changes needed.
+ * New upstream release.
+ * Drop patch markdown-etree.patch, present upstream.
- -- Debian Janitor <janitor@jelmer.uk> Sat, 29 Oct 2022 10:33:48 -0000
+ -- Debian Janitor <janitor@jelmer.uk> Tue, 20 Dec 2022 05:38:07 -0000
mkautodoc (0.1.0-4) unstable; urgency=medium
diff --git a/debian/patches/markdown-etree.patch b/debian/patches/markdown-etree.patch
deleted file mode 100644
index d65a7c9..0000000
--- a/debian/patches/markdown-etree.patch
+++ /dev/null
@@ -1,39 +0,0 @@
-diff --git a/mkautodoc/extension.py b/mkautodoc/extension.py
-index 86e70b3..64fe7fa 100644
---- a/mkautodoc/extension.py
-+++ b/mkautodoc/extension.py
-@@ -1,7 +1,7 @@
- from markdown import Markdown
- from markdown.extensions import Extension
- from markdown.blockprocessors import BlockProcessor
--from markdown.util import etree
-+from xml.etree import ElementTree as etree
- import importlib
- import inspect
- import re
-diff --git a/requirements.txt b/requirements.txt
-index 67ec1b1..8a7d94c 100644
---- a/requirements.txt
-+++ b/requirements.txt
-@@ -1,4 +1,4 @@
--markdown
-+-e .
-
- # Testing
- black
-diff --git a/setup.py b/setup.py
-index 8cb3b5b..8be283f 100644
---- a/setup.py
-+++ b/setup.py
-@@ -37,7 +37,7 @@ setup(
- author='Tom Christie',
- author_email='tom@tomchristie.com',
- packages=get_packages('mkautodoc'),
-- install_requires=[],
-+ install_requires=["Markdown"],
- python_requires='>=3.6',
- classifiers=[
- 'Development Status :: 3 - Alpha',
---
-2.30.2
-
diff --git a/debian/patches/series b/debian/patches/series
index 481fc76..e69de29 100644
--- a/debian/patches/series
+++ b/debian/patches/series
@@ -1 +0,0 @@
-markdown-etree.patch
diff --git a/mkautodoc/__init__.py b/mkautodoc/__init__.py
index 0c8c5d4..5dcbe96 100644
--- a/mkautodoc/__init__.py
+++ b/mkautodoc/__init__.py
@@ -1,5 +1,5 @@
from .extension import MKAutoDocExtension, makeExtension
-__version__ = "0.1.0"
+__version__ = "0.2.0"
__all__ = ["MKAutoDocExtension", "makeExtension"]
diff --git a/mkautodoc/extension.py b/mkautodoc/extension.py
index db64fd4..64fe7fa 100644
--- a/mkautodoc/extension.py
+++ b/mkautodoc/extension.py
@@ -1,7 +1,7 @@
from markdown import Markdown
from markdown.extensions import Extension
from markdown.blockprocessors import BlockProcessor
-from markdown.util import etree
+from xml.etree import ElementTree as etree
import importlib
import inspect
import re
@@ -66,7 +66,7 @@ def get_params(signature: inspect.Signature) -> typing.List[str]:
def last_iter(seq: typing.Sequence) -> typing.Iterator:
"""
- Given an sequence, return a two-tuple (item, is_last) iterable.
+ Given a sequence, return a two-tuple (item, is_last) iterable.
See: https://stackoverflow.com/a/1633483/596689
"""
@@ -182,6 +182,9 @@ class AutoDocProcessor(BlockProcessor):
if inspect.isclass(item):
qualifier_elem = etree.SubElement(signature_elem, "em")
qualifier_elem.text = "class "
+ elif inspect.iscoroutinefunction(item):
+ qualifier_elem = etree.SubElement(signature_elem, "em")
+ qualifier_elem.text = "async "
name_elem = etree.SubElement(signature_elem, "code")
if module_string:
diff --git a/requirements.txt b/requirements.txt
index 67ec1b1..8a7d94c 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,4 +1,4 @@
-markdown
+-e .
# Testing
black
diff --git a/scripts/install b/scripts/install
index 8e65b3a..52dccac 100755
--- a/scripts/install
+++ b/scripts/install
@@ -8,5 +8,6 @@ else
BIN_PATH="venv/bin/"
fi
+${BIN_PATH}pip install --upgrade pip
${BIN_PATH}pip install -r requirements.txt
${BIN_PATH}pip install -e .
diff --git a/setup.py b/setup.py
index 4e1ef00..4f90226 100644
--- a/setup.py
+++ b/setup.py
@@ -31,13 +31,13 @@ version = get_version('mkautodoc')
setup(
name='mkautodoc',
version=version,
- url='https://github.com/encode/mkautodoc',
+ url='https://github.com/tomchristie/mkautodoc',
license='BSD',
description='AutoDoc for MarkDown',
author='Tom Christie',
author_email='tom@tomchristie.com',
packages=get_packages('mkautodoc'),
- install_requires=[],
+ install_requires=["Markdown"],
python_requires='>=3.6',
classifiers=[
'Development Status :: 3 - Alpha',
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/assertions.py b/tests/assertions.py
new file mode 100644
index 0000000..14d21f6
--- /dev/null
+++ b/tests/assertions.py
@@ -0,0 +1,71 @@
+from xml import etree
+from xml.dom import minidom
+import textwrap
+
+
+def assert_xml_equal(xml_string, expected_xml_string):
+ """
+ Assert equality of two xml strings, particularly that the contents of
+ each string have the same elements, with the same attributes (e.g. class,
+ text) and the same non-xml string contents
+ """
+ # this prints a human-formatted string of what the test passed in -- useful
+ # if you need to modify test expectations after you've modified
+ # a rendering and tested it visually
+ print(to_readable_error_output(xml_string))
+
+ assert_elements_equal(
+ etree.ElementTree.fromstring(tostring(xml_string)),
+ etree.ElementTree.fromstring(tostring(expected_xml_string)),
+ )
+
+
+def assert_elements_equal(element, reference_element):
+ """
+ Assert, recursively, the equality of two etree objects.
+ """
+ assert (
+ element.text == reference_element.text
+ ), f"Text doesn't match: {element.text} =/= {reference_element.text}."
+ assert (
+ element.attrib == reference_element.attrib
+ ), f"Attrib doesn't match: {element.attrib} =/= {reference_element.attrib}"
+ assert len(element) == len(
+ reference_element
+ ), f"Expected {len(reference_element)} children but got {len(element)}"
+ for sub_element, reference_sub_element in zip(element, reference_element):
+ assert_elements_equal(sub_element, reference_sub_element)
+
+
+def tostring(xml_string):
+ """
+ Wraps `xml_string` in a div so it can be rendered, even if it has multiple roots.
+ """
+ return remove_indents(f"<div>{remove_indents(xml_string)}</div>").encode("utf-8")
+
+
+def to_readable_error_output(xml_string):
+ return textwrap.dedent(
+ "\n".join(
+ minidom.parseString(tostring(xml_string))
+ .toprettyxml(indent=" ")
+ .split("\n")[2:-2] # remove xml declaration and div added by `tostring`
+ )
+ ) # dent by " "
+
+
+def remove_indents(html):
+ """
+ Remove leading whitespace from a string
+
+ e.g.
+ input: output:
+ . <div> . <div>
+ . <p>Some Text</p> . <p>Some Text</p>
+ . <div> . <div>
+ . Some more text . Some more text
+ . </div> . </div>
+ . </div> . </div>
+ """
+ lines = [el.lstrip() for el in html.split("\n")]
+ return "".join([el for el in lines if el or el != "\n"])
diff --git a/tests/mocklib/mocklib.py b/tests/mocklib/mocklib.py
index 7b70eea..f41bb9b 100644
--- a/tests/mocklib/mocklib.py
+++ b/tests/mocklib/mocklib.py
@@ -24,3 +24,9 @@ class ExampleClass:
"""
This is a property with a *docstring*.
"""
+
+
+async def example_async_function():
+ """
+ This is a coroutine function as can be seen by the *async* keyword.
+ """
diff --git a/tests/test_extension.py b/tests/test_extension.py
index a9db6d0..4600361 100644
--- a/tests/test_extension.py
+++ b/tests/test_extension.py
@@ -1,4 +1,5 @@
import markdown
+from .assertions import assert_xml_equal
def test_docstring():
@@ -9,13 +10,55 @@ def test_docstring():
:docstring:
"""
output = markdown.markdown(content, extensions=["mkautodoc"])
- assert output.splitlines() == [
- "<h1>Example</h1>",
- '<div class="autodoc">',
- '<div class="autodoc-signature"><code>mocklib.<strong>example_function</strong></code><span class="autodoc-punctuation">(</span><em class="autodoc-param">a</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">b=None</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">*args</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">**kwargs</em><span class="autodoc-punctuation">)</span></div>',
- '<div class="autodoc-docstring"><p>This is a function with a <em>docstring</em>.</p></div>',
- "</div>",
- ]
+ assert_xml_equal(
+ output,
+ """
+<h1>Example</h1>
+<div class="autodoc">
+ <div class="autodoc-signature">
+ <code>
+ mocklib.
+ <strong>example_function</strong>
+ </code>
+ <span class="autodoc-punctuation">(</span>
+ <em class="autodoc-param">a</em>
+ <span class="autodoc-punctuation">, </span>
+ <em class="autodoc-param">b=None</em>
+ <span class="autodoc-punctuation">, </span>
+ <em class="autodoc-param">*args</em>
+ <span class="autodoc-punctuation">, </span>
+ <em class="autodoc-param">**kwargs</em>
+ <span class="autodoc-punctuation">)</span>
+ </div>
+ <div class="autodoc-docstring">
+ <p>
+ This is a function with a <em>docstring</em>.
+ </p>
+ </div>
+</div>""",
+ )
+
+
+def test_async_function():
+ content = """
+::: mocklib.example_async_function
+"""
+ output = markdown.markdown(content, extensions=["mkautodoc"])
+ assert_xml_equal(
+ output,
+ """
+<div class="autodoc">
+ <div class="autodoc-signature">
+ <em>async </em>
+ <code>
+ mocklib.
+ <strong>example_async_function</strong>
+ </code>
+ <span class="autodoc-punctuation">(</span>
+ <span class="autodoc-punctuation">)</span>
+ </div>
+</div>""",
+ )
def test_members():
@@ -27,16 +70,53 @@ def test_members():
:members:
"""
output = markdown.markdown(content, extensions=["mkautodoc"])
- assert output.splitlines() == [
- "<h1>Example</h1>",
- '<div class="autodoc">',
- '<div class="autodoc-signature"><em>class </em><code>mocklib.<strong>ExampleClass</strong></code><span class="autodoc-punctuation">(</span><span class="autodoc-punctuation">)</span></div>',
- '<div class="autodoc-docstring"><p>This is a class with a <em>docstring</em>.</p></div>',
- '<div class="autodoc-members">',
- '<div class="autodoc-signature"><code><strong>example_method</strong></code><span class="autodoc-punctuation">(</span><em class="autodoc-param">self</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">a</em><span class="autodoc-punctuation">, </span><em class="autodoc-param">b=None</em><span class="autodoc-punctuation">)</span></div>',
- '<div class="autodoc-docstring"><p>This is a method with a <em>docstring</em>.</p></div>',
- '<div class="autodoc-signature"><code><strong>example_property</strong></code></div>',
- '<div class="autodoc-docstring"><p>This is a property with a <em>docstring</em>.</p></div>',
- "</div>",
- "</div>",
- ]
+ assert_xml_equal(
+ output,
+ """
+<h1>Example</h1>
+<div class="autodoc">
+ <div class="autodoc-signature">
+ <em>class </em>
+ <code>
+ mocklib.
+ <strong>ExampleClass</strong>
+ </code>
+ <span class="autodoc-punctuation">(</span>
+ <span class="autodoc-punctuation">)</span>
+ </div>
+ <div class="autodoc-docstring">
+ <p>
+ This is a class with a <em>docstring</em>.
+ </p>
+ </div>
+ <div class="autodoc-members">
+ <div class="autodoc-signature">
+ <code>
+ <strong>example_method</strong>
+ </code>
+ <span class="autodoc-punctuation">(</span>
+ <em class="autodoc-param">self</em>
+ <span class="autodoc-punctuation">, </span>
+ <em class="autodoc-param">a</em>
+ <span class="autodoc-punctuation">, </span>
+ <em class="autodoc-param">b=None</em>
+ <span class="autodoc-punctuation">)</span>
+ </div>
+ <div class="autodoc-docstring">
+ <p>
+ This is a method with a <em>docstring</em>.
+ </p>
+ </div>
+ <div class="autodoc-signature">
+ <code>
+ <strong>example_property</strong>
+ </code>
+ </div>
+ <div class="autodoc-docstring">
+ <p>
+ This is a property with a <em>docstring</em>.
+ </p>
+ </div>
+ </div>
+</div>""",
+ )