docs: Document every option with examples and preview

README.md

@@ -24,6 +24,13 @@
 
 <p align="center"><img src="logo.png"></p>
 
+The Python handler uses [Griffe](https://mkdocstrings.github.io/griffe)
+to collect documentation from Python source code.
+The word "griffe" can sometimes be used instead of "signature" in French.
+Griffe is able to visit the Abstract Syntax Tree (AST) of the source code to extract useful information.
+It is also able to execute the code (by importing it) and introspect objects in memory
+when source code is not available. Finally, it can parse docstrings following different styles.
+
 ## Installation
 
 You can install this handler as a *mkdocstrings* extra:

docs/.glossary.md

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

docs/css/material.css

@@ -2,3 +2,30 @@
 .md-main__inner {
   margin-bottom: 1.5rem;
 }
+
+/* Custom admonition: preview */
+:root {
+  --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>')
+}
+
+.md-typeset .admonition.preview,
+.md-typeset details.preview {
+  border-color: rgb(220, 139, 240);
+}
+
+.md-typeset .preview>.admonition-title,
+.md-typeset .preview>summary {
+  background-color: rgba(142, 43, 155, 0.1);
+}
+
+.md-typeset .preview>.admonition-title::before,
+.md-typeset .preview>summary::before {
+  background-color: rgb(220, 139, 240);
+  -webkit-mask-image: var(--md-admonition-icon--preview);
+  mask-image: var(--md-admonition-icon--preview);
+}
+
+/* Avoid breaking parameters name, etc. in documentation table cells. */
+td code {
+  word-break: normal !important;
+}

docs/css/mkdocstrings.css

@@ -5,6 +5,7 @@ div.doc-contents:not(.first) {
 }
 
 /* Mark external links as such */
+a.external::after,
 a.autorefs-external::after {
   /* https://primer.style/octicons/arrow-up-right-24 */
   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 {
   border-radius: 100%;
   background-color: var(--md-typeset-a-color);
 }
+
+a.external:hover::after,
 a.autorefs-external:hover::after {
   background-color: var(--md-accent-fg-color);
-}
+}