Skip to content

Commit 07cbf0a

Browse files
pawamoypawamoy
authored
Add API docs to documentation
The API docs are auto-generated with mkdocstrings. The Google-style is used in docstrings to document parameters, return values, exceptions raised, etc.. Most of the docstrings throughout the codebase have been rewritten to be included in the documentations. Most objects have had type annotations added as well. While a significant portion of the code has received edits, there should be no changes to the code itself and therefore no changes in behavior. Co-authored-by @waylan who made most of the docstring edits.
1 parent 5a2fee3 commit 07cbf0a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+1980
-1065
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ target/
6464
.python-version
6565

6666
# virtualenv
67+
.venv/
6768
venv/
6869
ENV/
6970

‎.spell-dict

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ md
6969
merchantability
7070
metadata
7171
MkDocs
72+
mkdocstrings
7273
multi
7374
MultiMarkdown
7475
munge
@@ -102,6 +103,7 @@ refactor
102103
refactored
103104
refactors
104105
registerExtension
106+
resettable
105107
richeland
106108
RSS
107109
rST
@@ -126,6 +128,7 @@ stdout
126128
Stelios
127129
Stienstra
128130
subclasses
131+
submodules
129132
SuperFences
130133
svn
131134
Swartz

‎docs/changelog.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ links to the header, placing them after all other header content.
2727
* Refactor changelog to use the format defined at <https://keepachangelog.com/>.
2828
* Update the list of empty HTML tags (#1353).
2929
* Add customizable TOC title class to TOC extension (#1293).
30+
* Add API documentation of the code base which is generated by
31+
[mkdocstrings](https://mkdocstrings.github.io/) (#1220).
3032

3133
### Fixed
3234

‎docs/extensions/api.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -845,7 +845,7 @@ assert someitem in registry
845845

846846
: Add an item to the registry with the given name and priority.
847847

848-
Parameters:
848+
Arguments:
849849

850850
* `item`: The item being registered.
851851
* `name`: A string used to reference the item.

‎docs/mkdocstrings.css

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
/* Indentation. */
2+
div.doc-contents:not(.first) {
3+
padding-left: 25px;
4+
}
5+
6+
/* Mark external links as such. */
7+
a.external::after,
8+
a.autorefs-external::after {
9+
/* https://primer.style/octicons/arrow-up-right-24 */
10+
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>');
11+
-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>');
12+
content: ' ';
13+
14+
display: inline-block;
15+
vertical-align: middle;
16+
position: relative;
17+
18+
height: 1em;
19+
width: 1em;
20+
background-color: #005b81;
21+
}
22+
23+
a.external:hover::after,
24+
a.autorefs-external:hover::after {
25+
background-color: #e32e00;
26+
}
27+
28+
/* Customize custom links. */
29+
a.autorefs code {
30+
background-color: #ecf0f3;
31+
font-weight: normal;
32+
color: #005B81;
33+
}
34+
35+
a.autorefs:hover code {
36+
color: #E32E00;
37+
}
38+
39+
/* Customize labels. */
40+
.doc-label {
41+
border-radius: 15px;
42+
padding: 2px 8px;
43+
background-color: #f2f2f3;
44+
text-wrap: nowrap;
45+
}
46+
47+
.doc-label code {
48+
color: #444;
49+
}
50+
51+
.doc-label-deprecated {
52+
background-color: #ffe4e4;
53+
border: 1px solid #f66;
54+
}
55+
56+
/* No shadows in any code. */
57+
58+
code {
59+
text-shadow: none;
60+
}
61+
62+
/* Code spans in tables. */
63+
64+
table code {
65+
background-color: transparent !important;
66+
}
67+
68+
/* Style source links */
69+
a.doc-source-link {
70+
position: relative;
71+
float: right;
72+
border: 1px #005B81 solid;
73+
margin: 0 5px;
74+
padding: 0 5px;
75+
font-weight: normal;
76+
text-shadow: none;
77+
background-color: #f2f2f3;
78+
font-size: 1rem;
79+
}
80+
81+
a.doc-source-link:hover {
82+
text-decoration: none;
83+
border-color: #E32E00;
84+
}
85+
86+
/* Customize symbol names. */
87+
code.doc-symbol-attribute::after {
88+
content: "Attr";
89+
}
90+
91+
code.doc-symbol-function::after {
92+
content: "Func";
93+
}
94+
95+
code.doc-symbol-method::after {
96+
content: "Method";
97+
}
98+
99+
code.doc-symbol-class::after {
100+
content: "Class";
101+
}
102+
103+
code.doc-symbol-module::after {
104+
content: "Module";
105+
}

‎docs/templates/python/nature/attribute.html

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{% extends "_base/attribute.html" %}
2+
3+
{% block heading scoped %}
4+
<a class="doc-source-link" href="{{ config.source.repo }}/tree/{{ config.source.tag }}/{{ attribute.filepath }}#L{{ attribute.lineno }}{% if attribute.endlineno > attribute.lineno %}-L{{ attribute.endlineno }}{% endif %}" title='View source code on GitHub'>&lsaquo;&rsaquo;</a>
5+
{%+ filter highlight(language="python", inline=True) %}
6+
{{ attribute_name }}{% if attribute.annotation %}: {{ attribute.annotation }}{% endif %}
7+
{% endfilter %}
8+
{% endblock heading %}
9+
10+
{% block contents scoped %}
11+
{{ super() }}
12+
{% if attribute.value %}
13+
<p>Defined Value:</p>
14+
{%+ filter highlight(language="python", inline=False) %}
15+
{{ attribute.source }}
16+
{% endfilter %}
17+
{% endif %}
18+
{% endblock contents %}

‎docs/templates/python/nature/class.html

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{% extends "_base/class.html" %}
2+
3+
{% block heading scoped %}
4+
<a class="doc-source-link" href="{{ config.source.repo }}/tree/{{ config.source.tag }}/{{ class.filepath }}#L{{ class.lineno }}" title="{{ config.source.title }}">&lsaquo;&rsaquo;</a>
5+
{{ super() }}
6+
{% endblock heading %}

‎docs/templates/python/nature/docstring/admonition.html

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{{ log.debug("Rendering admonition") }}
2+
<div class="admonition {{ section.value.kind }}">
3+
<p class="admonition-title">{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}</p>
4+
{{ section.value.contents|convert_markdown(heading_level, html_id) }}
5+
</div>

‎docs/templates/python/nature/function.html

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{% extends "_base/function.html" %}
2+
3+
{% block heading scoped %}
4+
<a class="doc-source-link" href="{{ config.source.repo }}/tree/{{ config.source.tag }}/{{ function.filepath }}#L{{ function.lineno }}{% if function.endlineno > function.lineno %}-L{{ function.endlineno }}{% endif %}" title="{{ config.source.title }}">&lsaquo;&rsaquo;</a>
5+
{{ super() }}
6+
{% endblock heading %}

‎docs/templates/python/nature/module.html

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{% extends "_base/module.html" %}
2+
3+
{% block heading scoped %}
4+
<a class="doc-source-link" href="{{ config.source.repo }}/tree/{{ config.source.tag }}/{{ module.filepath }}" title="{{ config.source.title }}">&lsaquo;&rsaquo;</a>
5+
{{ super() }}
6+
{% endblock heading %}

‎markdown/__init__.py

Lines changed: 34 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,43 @@
1-
"""
2-
Python Markdown
1+
# Python Markdown
2+
3+
# A Python implementation of John Gruber's Markdown.
34

4-
A Python implementation of John Gruber's Markdown.
5+
# - Documentation: https://python-markdown.github.io/
6+
# - GitHub: https://github.com/Python-Markdown/markdown/
7+
# - PyPI: https://pypi.org/project/Markdown/
58

6-
Documentation: https://python-markdown.github.io/
7-
GitHub: https://github.com/Python-Markdown/markdown/
8-
PyPI: https://pypi.org/project/Markdown/
9+
# Started by Manfred Stienstra (http://www.dwerg.net/).
10+
# Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
11+
# Currently maintained by Waylan Limberg (https://github.com/waylan),
12+
# Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
913

10-
Started by Manfred Stienstra (http://www.dwerg.net/).
11-
Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
12-
Currently maintained by Waylan Limberg (https://github.com/waylan),
13-
Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
14+
# - Copyright 2007-2023 The Python Markdown Project (v. 1.7 and later)
15+
# - Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
16+
# - Copyright 2004 Manfred Stienstra (the original version)
1417

15-
Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
16-
Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
17-
Copyright 2004 Manfred Stienstra (the original version)
18+
# License: BSD (see LICENSE.md for details).
1819

19-
License: BSD (see LICENSE.md for details).
2020
"""
21+
Python-Markdown provides two public functions ([`markdown.markdown`][] and [`markdown.markdownFromFile`][])
22+
both of which wrap the public class [`markdown.Markdown`][]. All submodules support these public functions
23+
and class and/or provide extension support.
24+
25+
Modules:
26+
core: Core functionality.
27+
preprocessors: Pre-processors.
28+
blockparser: Core Markdown block parser.
29+
blockprocessors: Block processors.
30+
treeprocessors: Tree processors.
31+
inlinepatterns: Inline patterns.
32+
postprocessors: Post-processors.
33+
serializers: Serializers.
34+
util: Utility functions.
35+
htmlparser: HTML parser.
36+
test_tools: Testing utilities.
37+
extensions: Markdown extensions.
38+
"""
39+
40+
from __future__ import annotations
2141

2242
from .core import Markdown, markdown, markdownFromFile
2343
from .__meta__ import __version__, __version_info__ # noqa

‎markdown/__main__.py

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,23 @@
1-
"""
2-
Python Markdown
1+
# Python Markdown
32

4-
A Python implementation of John Gruber's Markdown.
3+
# A Python implementation of John Gruber's Markdown.
54

6-
Documentation: https://python-markdown.github.io/
7-
GitHub: https://github.com/Python-Markdown/markdown/
8-
PyPI: https://pypi.org/project/Markdown/
5+
# Documentation: https://python-markdown.github.io/
6+
# GitHub: https://github.com/Python-Markdown/markdown/
7+
# PyPI: https://pypi.org/project/Markdown/
98

10-
Started by Manfred Stienstra (http://www.dwerg.net/).
11-
Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
12-
Currently maintained by Waylan Limberg (https://github.com/waylan),
13-
Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
9+
# Started by Manfred Stienstra (http://www.dwerg.net/).
10+
# Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
11+
# Currently maintained by Waylan Limberg (https://github.com/waylan),
12+
# Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
1413

15-
Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
16-
Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
17-
Copyright 2004 Manfred Stienstra (the original version)
14+
# Copyright 2007-2023 The Python Markdown Project (v. 1.7 and later)
15+
# Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
16+
# Copyright 2004 Manfred Stienstra (the original version)
1817

19-
License: BSD (see LICENSE.md for details).
20-
"""
18+
# License: BSD (see LICENSE.md for details).
19+
20+
from __future__ import annotations
2121

2222
import sys
2323
import optparse

‎markdown/__meta__.py

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,21 @@
1-
"""
2-
Python Markdown
1+
# Python Markdown
32

4-
A Python implementation of John Gruber's Markdown.
3+
# A Python implementation of John Gruber's Markdown.
54

6-
Documentation: https://python-markdown.github.io/
7-
GitHub: https://github.com/Python-Markdown/markdown/
8-
PyPI: https://pypi.org/project/Markdown/
5+
# Documentation: https://python-markdown.github.io/
6+
# GitHub: https://github.com/Python-Markdown/markdown/
7+
# PyPI: https://pypi.org/project/Markdown/
98

10-
Started by Manfred Stienstra (http://www.dwerg.net/).
11-
Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
12-
Currently maintained by Waylan Limberg (https://github.com/waylan),
13-
Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
9+
# Started by Manfred Stienstra (http://www.dwerg.net/).
10+
# Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org).
11+
# Currently maintained by Waylan Limberg (https://github.com/waylan),
12+
# Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser).
1413

15-
Copyright 2007-2018 The Python Markdown Project (v. 1.7 and later)
16-
Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
17-
Copyright 2004 Manfred Stienstra (the original version)
14+
# Copyright 2007-2023 The Python Markdown Project (v. 1.7 and later)
15+
# Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b)
16+
# Copyright 2004 Manfred Stienstra (the original version)
1817

19-
License: BSD (see LICENSE.md for details).
20-
"""
18+
# License: BSD (see LICENSE.md for details).
2119

2220
# __version_info__ format:
2321
# (major, minor, patch, dev/alpha/beta/rc/final, #)
@@ -26,11 +24,15 @@
2624
# (1, 2, 0, 'beta', 2) => "1.2b2"
2725
# (1, 2, 0, 'rc', 4) => "1.2rc4"
2826
# (1, 2, 0, 'final', 0) => "1.2"
27+
28+
from __future__ import annotations
29+
30+
2931
__version_info__ = (3, 4, 4, 'final', 0)
3032

3133

3234
def _get_version(version_info):
33-
" Returns a PEP 440-compliant version number from version_info. "
35+
" Returns a PEP 440-compliant version number from `version_info`. "
3436
assert len(version_info) == 5
3537
assert version_info[3] in ('dev', 'alpha', 'beta', 'rc', 'final')
3638

0 commit comments

Comments
 (0)