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 %}

0 commit comments

Comments
 (0)