Skip to content

Commit

Permalink
Add API docs to documentation
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
pawamoy authored Oct 6, 2023
1 parent 5a2fee3 commit 07cbf0a
Show file tree
Hide file tree
Showing 72 changed files with 1,980 additions and 1,065 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ target/
.python-version

# virtualenv
.venv/
venv/
ENV/

Expand Down
3 changes: 3 additions & 0 deletions .spell-dict
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ md
merchantability
metadata
MkDocs
mkdocstrings
multi
MultiMarkdown
munge
Expand Down Expand Up @@ -102,6 +103,7 @@ refactor
refactored
refactors
registerExtension
resettable
richeland
RSS
rST
Expand All @@ -126,6 +128,7 @@ stdout
Stelios
Stienstra
subclasses
submodules
SuperFences
svn
Swartz
Expand Down
2 changes: 2 additions & 0 deletions docs/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ links to the header, placing them after all other header content.
* Refactor changelog to use the format defined at <https://keepachangelog.com/>.
* Update the list of empty HTML tags (#1353).
* Add customizable TOC title class to TOC extension (#1293).
* Add API documentation of the code base which is generated by
[mkdocstrings](https://mkdocstrings.github.io/) (#1220).

### Fixed

Expand Down
2 changes: 1 addition & 1 deletion docs/extensions/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
105 changes: 105 additions & 0 deletions docs/mkdocstrings.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
/* 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 custom links. */
a.autorefs code {
background-color: #ecf0f3;
font-weight: normal;
color: #005B81;
}

a.autorefs:hover code {
color: #E32E00;
}

/* Customize labels. */
.doc-label {
border-radius: 15px;
padding: 2px 8px;
background-color: #f2f2f3;
text-wrap: nowrap;
}

.doc-label code {
color: #444;
}

.doc-label-deprecated {
background-color: #ffe4e4;
border: 1px solid #f66;
}

/* No shadows in any code. */

code {
text-shadow: none;
}

/* Code spans in tables. */

table code {
background-color: transparent !important;
}

/* Style source links */
a.doc-source-link {
position: relative;
float: right;
border: 1px #005B81 solid;
margin: 0 5px;
padding: 0 5px;
font-weight: normal;
text-shadow: none;
background-color: #f2f2f3;
font-size: 1rem;
}

a.doc-source-link:hover {
text-decoration: none;
border-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";
}
18 changes: 18 additions & 0 deletions docs/templates/python/nature/attribute.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
{% extends "_base/attribute.html" %}

{% block heading scoped %}
<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>
{%+ filter highlight(language="python", inline=True) %}
{{ attribute_name }}{% if attribute.annotation %}: {{ attribute.annotation }}{% endif %}
{% endfilter %}
{% endblock heading %}

{% block contents scoped %}
{{ super() }}
{% if attribute.value %}
<p>Defined Value:</p>
{%+ filter highlight(language="python", inline=False) %}
{{ attribute.source }}
{% endfilter %}
{% endif %}
{% endblock contents %}
6 changes: 6 additions & 0 deletions docs/templates/python/nature/class.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{% extends "_base/class.html" %}

{% block heading scoped %}
<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>
{{ super() }}
{% endblock heading %}
5 changes: 5 additions & 0 deletions docs/templates/python/nature/docstring/admonition.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{{ log.debug("Rendering admonition") }}
<div class="admonition {{ section.value.kind }}">
<p class="admonition-title">{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}</p>
{{ section.value.contents|convert_markdown(heading_level, html_id) }}
</div>
6 changes: 6 additions & 0 deletions docs/templates/python/nature/function.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{% extends "_base/function.html" %}

{% block heading scoped %}
<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>
{{ super() }}
{% endblock heading %}
6 changes: 6 additions & 0 deletions docs/templates/python/nature/module.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{% extends "_base/module.html" %}

{% block heading scoped %}
<a class="doc-source-link" href="{{ config.source.repo }}/tree/{{ config.source.tag }}/{{ module.filepath }}" title="{{ config.source.title }}">&lsaquo;&rsaquo;</a>
{{ super() }}
{% endblock heading %}
48 changes: 34 additions & 14 deletions markdown/__init__.py
Original file line number Diff line number Diff line change
@@ -1,23 +1,43 @@
"""
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-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)

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).
"""
Python-Markdown provides two public functions ([`markdown.markdown`][] and [`markdown.markdownFromFile`][])
both of which wrap the public class [`markdown.Markdown`][]. All submodules support these public functions
and class and/or provide extension support.
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
Expand Down
30 changes: 15 additions & 15 deletions markdown/__main__.py
Original file line number Diff line number Diff line change
@@ -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
Expand Down
34 changes: 18 additions & 16 deletions markdown/__meta__.py
Original file line number Diff line number Diff line change
@@ -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, #)
Expand All @@ -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')

Expand Down
Loading

0 comments on commit 07cbf0a

Please sign in to comment.