Skip to content

Commit 1a3580a

Browse files
pawamoypawamoy
committed
docs: Update docs
1 parent ea73a74 commit 1a3580a

File tree

3 files changed

+49
-62
lines changed

3 files changed

+49
-62
lines changed

‎docs/.glossary.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,6 @@
77
[ReadTheDocs Sphinx theme]: https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html
88
[Spacy's documentation]: https://spacy.io/api/doc/
99
[Black]: https://pypi.org/project/black/
10+
[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material
1011

1112
*[ToC]: Table of Contents

‎docs/css/material.css‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
/* Custom admonition: preview */
77
: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>')
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>');
99
}
1010

1111
.md-typeset .admonition.preview,
@@ -23,9 +23,4 @@
2323
background-color: rgb(220, 139, 240);
2424
-webkit-mask-image: var(--md-admonition-icon--preview);
2525
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;
3126
}

‎docs/usage/customization.md‎

Lines changed: 47 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -29,76 +29,41 @@ The following CSS classes are used in the generated HTML:
2929

3030
//// tab | CSS
3131
```css
32-
.doc-label { border-radius: 15px; padding: 0 5px; }
33-
.doc-label-special { background-color: blue; color: white; }
34-
.doc-label-private { background-color: red; color: white; }
35-
.doc-label-property { background-color: green; color: white; }
36-
.doc-label-read-only { background-color: yellow; color: black; }
32+
.doc-label { border-radius: 15px; padding: 2px 8px; font-weight: bold; }
33+
.doc-label-special { background-color: #3330E4; color: white; }
34+
.doc-label-private { background-color: #F637EC; color: white; }
35+
.doc-label-property { background-color: #FBB454; color: black; }
36+
.doc-label-read-only { background-color: #FAEA48; color: black; }
3737
```
3838
////
3939

4040
//// tab | Result
4141
<style>
42-
.lbl { border-radius: 15px; padding: 0 5px; }
42+
.lbl { border-radius: 15px; padding: 2px 8px; font-weight: bold; }
4343
</style>
44-
<h3 style="margin: 0;"><span>
45-
<small class="lbl" style="background-color: blue; color: white !important;">special</small>
46-
<small class="lbl" style="background-color: red; color: white !important;">private</small>
47-
<small class="lbl" style="background-color: green; color: white !important;">property</small>
48-
<small class="lbl" style="background-color: yellow; color: black !important;">read-only</small>
49-
</span></h3>
44+
<h3 style="margin: 0;">
45+
<p>
46+
<small class="lbl" style="background-color: #3330E4; color: white !important;">special</small>
47+
<small class="lbl" style="background-color: #F637EC; color: white !important;">private</small>
48+
<small class="lbl" style="background-color: #FBB454; color: black !important;">property</small>
49+
<small class="lbl" style="background-color: #FAEA48; color: black !important;">read-only</small>
50+
</p>
51+
</h3>
5052
////
5153

5254
///
5355

54-
55-
### Recommended style (Material)
56-
57-
Here are some CSS rules for the
58-
[*Material for MkDocs*](https://squidfunk.github.io/mkdocs-material/) theme:
59-
60-
```css
61-
--8<-- "docs/css/mkdocstrings.css"
62-
```
63-
64-
### Recommended style (ReadTheDocs)
65-
66-
Here are some CSS rules for the built-in *ReadTheDocs* theme:
67-
68-
```css
69-
/* Indentation. */
70-
div.doc-contents:not(.first) {
71-
padding-left: 25px;
72-
border-left: .05rem solid rgba(200, 200, 200, 0.2);
73-
}
74-
```
75-
7656
## Templates
7757

7858
Templates are organized into the following tree:
7959

80-
```tree result="text"
81-
theme/
82-
attribute.html
83-
children.html
84-
class.html
85-
docstring/
86-
admonition.html
87-
attributes.html
88-
examples.html
89-
other_parameters.html
90-
parameters.html
91-
raises.html
92-
receives.html
93-
returns.html
94-
warns.html
95-
yields.html
96-
docstring.html
97-
expression.html
98-
function.html
99-
labels.html
100-
module.html
101-
signature.html
60+
```python exec="1" result="tree"
61+
from pathlib import Path
62+
63+
basedir = "src/mkdocstrings_handlers/python/templates/material"
64+
print("theme/")
65+
for filepath in sorted(path for path in Path(basedir).rglob("*") if "_base" not in str(path) and path.suffix != ".css"):
66+
print(" " * (len(filepath.relative_to(basedir).parent.parts) + 1) + filepath.name + ("/" if filepath.is_dir() else ""))
10267
```
10368

10469
See them [in the repository](https://github.com/mkdocstrings/python/tree/master/src/mkdocstrings_handlers/python/templates/).
@@ -131,3 +96,29 @@ without having to fully copy-paste it into your project:
13196
```
13297

13398
WARNING: **Block-level customization is not ready yet. We welcome [suggestions](https://github.com/mkdocstrings/python/issues/new).**
99+
100+
## Style recommendations
101+
102+
<a id="recommended-style-material"></a>
103+
104+
### Material
105+
106+
Here are some CSS rules for the [Material for MkDocs] theme:
107+
108+
```css
109+
--8<-- "docs/css/mkdocstrings.css"
110+
```
111+
112+
<a id="recommended-style-readthedocs"></a>
113+
114+
### ReadTheDocs
115+
116+
Here are some CSS rules for the built-in ReadTheDocs theme:
117+
118+
```css
119+
/* Indentation. */
120+
div.doc-contents:not(.first) {
121+
padding-left: 25px;
122+
border-left: .05rem solid rgba(200, 200, 200, 0.2);
123+
}
124+
```

0 commit comments

Comments
 (0)