Skip to content

Commit 54ccd5b

Browse files
pawamoypawamoy
committed
docs: Document every option with examples and preview
1 parent 40f2f26 commit 54ccd5b

File tree

16 files changed

+2442
-115
lines changed

16 files changed

+2442
-115
lines changed

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,13 @@
2424

2525
<p align="center"><img src="logo.png"></p>
2626

27+
The Python handler uses [Griffe](https://mkdocstrings.github.io/griffe)
28+
to collect documentation from Python source code.
29+
The word "griffe" can sometimes be used instead of "signature" in French.
30+
Griffe is able to visit the Abstract Syntax Tree (AST) of the source code to extract useful information.
31+
It is also able to execute the code (by importing it) and introspect objects in memory
32+
when source code is not available. Finally, it can parse docstrings following different styles.
33+
2734
## Installation
2835

2936
You can install this handler as a *mkdocstrings* extra:

‎docs/.glossary.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[__all__]: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package
2+
[class template]: https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/templates/material/_base/class.html
3+
[function template]: https://github.com/mkdocstrings/python/blob/master/src/mkdocstrings_handlers/python/templates/material/_base/function.html
4+
[autodoc syntax]: https://mkdocstrings.github.io/usage/#autodoc-syntax
5+
[autopages recipe]: https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
6+
[Griffe]: https://github.com/mkdocstrings/griffe
7+
[ReadTheDocs Sphinx theme]: https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html
8+
[Spacy's documentation]: https://spacy.io/api/doc/
9+
[Black]: https://pypi.org/project/black/
10+
11+
*[ToC]: Table of Contents

‎docs/css/material.css‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,30 @@
22
.md-main__inner {
33
margin-bottom: 1.5rem;
44
}
5+
6+
/* Custom admonition: preview */
7+
:root {
8+
--md-admonition-icon--preview: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M15.5 12a3.5 3.5 0 1 1-7 0 3.5 3.5 0 0 1 7 0Z"/><path d="M12 3.5c3.432 0 6.124 1.534 8.054 3.241 1.926 1.703 3.132 3.61 3.616 4.46a1.6 1.6 0 0 1 0 1.598c-.484.85-1.69 2.757-3.616 4.461-1.929 1.706-4.622 3.24-8.054 3.24-3.432 0-6.124-1.534-8.054-3.24C2.02 15.558.814 13.65.33 12.8a1.6 1.6 0 0 1 0-1.598c.484-.85 1.69-2.757 3.616-4.462C5.875 5.034 8.568 3.5 12 3.5ZM1.633 11.945a.115.115 0 0 0-.017.055c.001.02.006.039.017.056.441.774 1.551 2.527 3.307 4.08C6.691 17.685 9.045 19 12 19c2.955 0 5.31-1.315 7.06-2.864 1.756-1.553 2.866-3.306 3.307-4.08a.111.111 0 0 0 .017-.056.111.111 0 0 0-.017-.056c-.441-.773-1.551-2.527-3.307-4.08C17.309 6.315 14.955 5 12 5 9.045 5 6.69 6.314 4.94 7.865c-1.756 1.552-2.866 3.306-3.307 4.08Z"/></svg>')
9+
}
10+
11+
.md-typeset .admonition.preview,
12+
.md-typeset details.preview {
13+
border-color: rgb(220, 139, 240);
14+
}
15+
16+
.md-typeset .preview>.admonition-title,
17+
.md-typeset .preview>summary {
18+
background-color: rgba(142, 43, 155, 0.1);
19+
}
20+
21+
.md-typeset .preview>.admonition-title::before,
22+
.md-typeset .preview>summary::before {
23+
background-color: rgb(220, 139, 240);
24+
-webkit-mask-image: var(--md-admonition-icon--preview);
25+
mask-image: var(--md-admonition-icon--preview);
26+
}
27+
28+
/* Avoid breaking parameters name, etc. in documentation table cells. */
29+
td code {
30+
word-break: normal !important;
31+
}

‎docs/css/mkdocstrings.css‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ div.doc-contents:not(.first) {
55
}
66

77
/* Mark external links as such */
8+
a.external::after,
89
a.autorefs-external::after {
910
/* https://primer.style/octicons/arrow-up-right-24 */
1011
background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="rgb(0, 0, 0)" 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>');
@@ -21,6 +22,8 @@ a.autorefs-external::after {
2122
border-radius: 100%;
2223
background-color: var(--md-typeset-a-color);
2324
}
25+
26+
a.external:hover::after,
2427
a.autorefs-external:hover::after {
2528
background-color: var(--md-accent-fg-color);
26-
}
29+
}

0 commit comments

Comments
 (0)