Skip to content

Commit a2392aa

Browse files
pawamoypawamoy
committed
feat: Declare and use symbols for all kinds of objects
1 parent 3719e62 commit a2392aa

20 files changed

+524
-298
lines changed

‎docs/usage/configuration/headings.md

+102-46
Original file line numberDiff line numberDiff line change
@@ -78,11 +78,23 @@ plugins:
7878
Show the symbol type in headings.
7979

8080
This option will prefix headings with
81-
<code class="doc-symbol doc-symbol-attribute"></code>,
82-
<code class="doc-symbol doc-symbol-function"></code>,
83-
<code class="doc-symbol doc-symbol-method"></code>,
84-
<code class="doc-symbol doc-symbol-class"></code> or
85-
<code class="doc-symbol doc-symbol-module"></code> types.
81+
<code class="doc-symbol doc-symbol-ts-accessor"></code>,
82+
<code class="doc-symbol doc-symbol-ts-attribute"></code>,
83+
<code class="doc-symbol doc-symbol-ts-class"></code>,
84+
<code class="doc-symbol doc-symbol-ts-constructor"></code>,
85+
<code class="doc-symbol doc-symbol-ts-data"></code>,
86+
<code class="doc-symbol doc-symbol-ts-enum"></code>,
87+
<code class="doc-symbol doc-symbol-ts-enum_member"></code>,
88+
<code class="doc-symbol doc-symbol-ts-interface"></code>,
89+
<code class="doc-symbol doc-symbol-ts-method"></code>,
90+
<code class="doc-symbol doc-symbol-ts-module"></code>,
91+
<code class="doc-symbol doc-symbol-ts-namespace"></code>,
92+
<code class="doc-symbol doc-symbol-ts-parameter"></code>,
93+
<code class="doc-symbol doc-symbol-ts-project"></code>,
94+
<code class="doc-symbol doc-symbol-ts-property"></code>,
95+
<code class="doc-symbol doc-symbol-ts-type"></code>,
96+
<code class="doc-symbol doc-symbol-ts-type_alias"></code> or
97+
<code class="doc-symbol doc-symbol-ts-variable"></code> types.
8698
See also [`show_symbol_type_toc`][show_symbol_type_toc].
8799

88100
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
@@ -106,29 +118,43 @@ plugins:
106118
type: preview
107119

108120
//// tab | With symbol type in headings
109-
<h1><code class="doc-symbol doc-symbol-module"></code> <code>module</code></h1>
110-
<p>Docstring of the module.</p>
111-
<h2><code class="doc-symbol doc-symbol-attribute"></code> <code>attribute</code></h2>
112-
<p>Docstring of the module attribute.</p>
113-
<h2><code class="doc-symbol doc-symbol-function"></code> <code>function</code></h2>
114-
<p>Docstring of the function.</p>
115-
<h2><code class="doc-symbol doc-symbol-class"></code> <code>Class</code></h2>
116-
<p>Docstring of the class.</p>
117-
<h3><code class="doc-symbol doc-symbol-method"></code> <code>method</code></h3>
118-
<p>Docstring of the method.</p>
121+
<h2><code class="doc-symbol doc-symbol-ts-accessor"></code> <code>foo</code></h2><p>Docstring of the accessor.</p>
122+
<h2><code class="doc-symbol doc-symbol-ts-attribute"></code> <code>foo</code></h2><p>Docstring of the attribute.</p>
123+
<h2><code class="doc-symbol doc-symbol-ts-class"></code> <code>Foo</code></h2><p>Docstring of the class.</p>
124+
<h2><code class="doc-symbol doc-symbol-ts-constructor"></code> <code>foo</code></h2><p>Docstring of the constructor.</p>
125+
<h2><code class="doc-symbol doc-symbol-ts-data"></code> <code>foo</code></h2><p>Docstring of the data.</p>
126+
<h2><code class="doc-symbol doc-symbol-ts-enum"></code> <code>Foo</code></h2><p>Docstring of the enum.</p>
127+
<h2><code class="doc-symbol doc-symbol-ts-enum_member"></code> <code>foo</code></h2><p>Docstring of the enum member.</p>
128+
<h2><code class="doc-symbol doc-symbol-ts-interface"></code> <code>Foo</code></h2><p>Docstring of the interface.</p>
129+
<h2><code class="doc-symbol doc-symbol-ts-method"></code> <code>foo</code></h2><p>Docstring of the method.</p>
130+
<h2><code class="doc-symbol doc-symbol-ts-module"></code> <code>foo</code></h2><p>Docstring of the module.</p>
131+
<h2><code class="doc-symbol doc-symbol-ts-namespace"></code> <code>Foo</code></h2><p>Docstring of the namespace.</p>
132+
<h2><code class="doc-symbol doc-symbol-ts-parameter"></code> <code>foo</code></h2><p>Docstring of the parameter.</p>
133+
<h2><code class="doc-symbol doc-symbol-ts-project"></code> <code>foo</code></h2><p>Docstring of the project.</p>
134+
<h2><code class="doc-symbol doc-symbol-ts-property"></code> <code>foo</code></h2><p>Docstring of the property.</p>
135+
<h2><code class="doc-symbol doc-symbol-ts-type"></code> <code>Foo</code></h2><p>Docstring of the type.</p>
136+
<h2><code class="doc-symbol doc-symbol-ts-type_alias"></code> <code>Foo</code></h2><p>Docstring of the type alias.</p>
137+
<h2><code class="doc-symbol doc-symbol-ts-variable"></code> <code>foo</code></h2><p>Docstring of the variable.</p>
119138
////
120139

121140
//// tab | Without symbol type in headings
122-
<h1><code>module</code></h1>
123-
<p>Docstring of the module.</p>
124-
<h2><code>attribute</code></h2>
125-
<p>Docstring of the module attribute.</p>
126-
<h2><code>function</code></h2>
127-
<p>Docstring of the function.</p>
128-
<h2><code>Class</code></h2>
129-
<p>Docstring of the class.</p>
130-
<h3><code>method</code></h3>
131-
<p>Docstring of the method.</p>
141+
<h2><code>foo</code></h2><p>Docstring of the accessor.</p>
142+
<h2><code>foo</code></h2><p>Docstring of the attribute.</p>
143+
<h2><code>Foo</code></h2><p>Docstring of the class.</p>
144+
<h2><code>foo</code></h2><p>Docstring of the constructor.</p>
145+
<h2><code>foo</code></h2><p>Docstring of the data.</p>
146+
<h2><code>Foo</code></h2><p>Docstring of the enum.</p>
147+
<h2><code>foo</code></h2><p>Docstring of the enum member.</p>
148+
<h2><code>Foo</code></h2><p>Docstring of the interface.</p>
149+
<h2><code>foo</code></h2><p>Docstring of the method.</p>
150+
<h2><code>foo</code></h2><p>Docstring of the module.</p>
151+
<h2><code>Foo</code></h2><p>Docstring of the namespace.</p>
152+
<h2><code>foo</code></h2><p>Docstring of the parameter.</p>
153+
<h2><code>foo</code></h2><p>Docstring of the project.</p>
154+
<h2><code>foo</code></h2><p>Docstring of the property.</p>
155+
<h2><code>Foo</code></h2><p>Docstring of the type.</p>
156+
<h2><code>Foo</code></h2><p>Docstring of the type alias.</p>
157+
<h2><code>foo</code></h2><p>Docstring of the variable.</p>
132158
////
133159
///
134160

@@ -140,11 +166,23 @@ plugins:
140166
Show the symbol type in the Table of Contents.
141167

142168
This option will prefix items in the ToC with
143-
<code class="doc-symbol doc-symbol-attribute"></code>,
144-
<code class="doc-symbol doc-symbol-function"></code>,
145-
<code class="doc-symbol doc-symbol-method"></code>,
146-
<code class="doc-symbol doc-symbol-class"></code> or
147-
<code class="doc-symbol doc-symbol-module"></code> types.
169+
<code class="doc-symbol doc-symbol-ts-accessor"></code>,
170+
<code class="doc-symbol doc-symbol-ts-attribute"></code>,
171+
<code class="doc-symbol doc-symbol-ts-class"></code>,
172+
<code class="doc-symbol doc-symbol-ts-constructor"></code>,
173+
<code class="doc-symbol doc-symbol-ts-data"></code>,
174+
<code class="doc-symbol doc-symbol-ts-enum"></code>,
175+
<code class="doc-symbol doc-symbol-ts-enum_member"></code>,
176+
<code class="doc-symbol doc-symbol-ts-interface"></code>,
177+
<code class="doc-symbol doc-symbol-ts-method"></code>,
178+
<code class="doc-symbol doc-symbol-ts-module"></code>,
179+
<code class="doc-symbol doc-symbol-ts-namespace"></code>,
180+
<code class="doc-symbol doc-symbol-ts-parameter"></code>,
181+
<code class="doc-symbol doc-symbol-ts-project"></code>,
182+
<code class="doc-symbol doc-symbol-ts-property"></code>,
183+
<code class="doc-symbol doc-symbol-ts-type"></code>,
184+
<code class="doc-symbol doc-symbol-ts-type_alias"></code> or
185+
<code class="doc-symbol doc-symbol-ts-variable"></code> types.
148186
See also [`show_symbol_type_heading`][show_symbol_type_heading].
149187

150188
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
@@ -169,27 +207,45 @@ plugins:
169207

170208
//// tab | With symbol type in ToC
171209
<ul style="list-style: none;">
172-
<li><code class="doc-symbol doc-symbol-module"></code> module</li>
173-
<li><code class="doc-symbol doc-symbol-attribute"></code> attribute</li>
174-
<li><code class="doc-symbol doc-symbol-function"></code> function</li>
175-
<li><code class="doc-symbol doc-symbol-class"></code> Class
176-
<ul style="list-style: none;">
177-
<li><code class="doc-symbol doc-symbol-method"></code> method</li>
178-
</ul>
179-
</li>
210+
<li><code class="doc-symbol doc-symbol-ts-accessor"></code> foo</li>
211+
<li><code class="doc-symbol doc-symbol-ts-attribute"></code> foo</li>
212+
<li><code class="doc-symbol doc-symbol-ts-class"></code> Foo</li>
213+
<li><code class="doc-symbol doc-symbol-ts-constructor"></code> foo</li>
214+
<li><code class="doc-symbol doc-symbol-ts-data"></code> foo</li>
215+
<li><code class="doc-symbol doc-symbol-ts-enum"></code> Foo</li>
216+
<li><code class="doc-symbol doc-symbol-ts-enum_member"></code> foo</li>
217+
<li><code class="doc-symbol doc-symbol-ts-interface"></code> Foo</li>
218+
<li><code class="doc-symbol doc-symbol-ts-method"></code> foo</li>
219+
<li><code class="doc-symbol doc-symbol-ts-module"></code> foo</li>
220+
<li><code class="doc-symbol doc-symbol-ts-namespace"></code> Foo</li>
221+
<li><code class="doc-symbol doc-symbol-ts-parameter"></code> foo</li>
222+
<li><code class="doc-symbol doc-symbol-ts-project"></code> foo</li>
223+
<li><code class="doc-symbol doc-symbol-ts-property"></code> foo</li>
224+
<li><code class="doc-symbol doc-symbol-ts-type"></code> Foo</li>
225+
<li><code class="doc-symbol doc-symbol-ts-type_alias"></code> Foo</code></li>
226+
<li><code class="doc-symbol doc-symbol-ts-variable"></code> foo</code></li>
180227
</ul>
181228
////
182229

183230
//// tab | Without symbol type in ToC
184231
<ul style="list-style: none;">
185-
<li>module</li>
186-
<li>attribute</li>
187-
<li>function</li>
188-
<li>Class
189-
<ul style="list-style: none;">
190-
<li>method</li>
191-
</ul>
192-
</li>
232+
<li>foo</li>
233+
<li>foo</li>
234+
<li>Foo</li>
235+
<li>foo</li>
236+
<li>foo</li>
237+
<li>Foo</li>
238+
<li>foo</li>
239+
<li>Foo</li>
240+
<li>foo</li>
241+
<li>foo</li>
242+
<li>Foo</li>
243+
<li>foo</li>
244+
<li>foo</li>
245+
<li>foo</li>
246+
<li>Foo</li>
247+
<li>Foo</li>
248+
<li>foo</li>
193249
</ul>
194250
////
195251
///

‎docs/usage/customization.md

+86-35
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,12 @@
11
# Customization
22

3-
It is possible to customize the output of the generated documentation with CSS
4-
and/or by overriding templates.
3+
It is possible to customize the output of the generated documentation with CSS and/or by overriding templates.
54

65
## CSS classes
76

8-
Our templates add [CSS](https://www.w3schools.com/Css/) classes to many HTML elements
9-
to make it possible for users to customize the resulting look and feel.
7+
Our templates add [CSS](https://www.w3schools.com/Css/) classes to many HTML elements to make it possible for users to customize the resulting look and feel.
108

11-
To add CSS rules and style mkdocstrings' output,
12-
put them in a CSS file in your docs folder, for example in `docs/css/mkdocstrings.css`,
13-
and reference this file in [MkDocs' `extra_css` configuration option](https://www.mkdocs.org/user-guide/configuration/#extra_css):
9+
To add CSS rules and style mkdocstrings' output, put them in a CSS file in your docs folder, for example in `docs/css/mkdocstrings.css`, and reference this file in [MkDocs' `extra_css` configuration option](https://www.mkdocs.org/user-guide/configuration/#extra_css):
1410

1511
```yaml title="mkdocs.yml"
1612
extra_css:
@@ -29,34 +25,92 @@ Example:
2925

3026
### Colors
3127

32-
You can customize the colors of the symbol types
33-
(see [`show_symbol_type_heading`][show_symbol_type_heading] and [`show_symbol_type_toc`][show_symbol_type_toc])
34-
by overriding the values of our CSS variables, for example:
28+
You can customize the colors of the symbol types (see [`show_symbol_type_heading`][show_symbol_type_heading] and [`show_symbol_type_toc`][show_symbol_type_toc]) by overriding the values of our CSS variables, for example:
3529

3630
```css title="docs/css/mkdocstrings.css"
3731
[data-md-color-scheme="default"] {
38-
--doc-symbol-data-fg-color: #d1b619;
39-
40-
--doc-symbol-data-bg-color: #d1b6191a;
32+
--doc-symbol-ts-accessor-fg-color: #6f42c1
33+
--doc-symbol-ts-attribute-fg-color: #6f42c1
34+
--doc-symbol-ts-class-fg-color: #22863a
35+
--doc-symbol-ts-constructor-fg-color: #1f66ff
36+
--doc-symbol-ts-data-fg-color: #0366d6
37+
--doc-symbol-ts-enum-fg-color: #6f42c1
38+
--doc-symbol-ts-enum_member-fg-color: #f0ad4e
39+
--doc-symbol-ts-interface-fg-color: #6f42c1
40+
--doc-symbol-ts-method-fg-color: #0366d6
41+
--doc-symbol-ts-module-fg-color: #0366d6
42+
--doc-symbol-ts-namespace-fg-color: #0366d6
43+
--doc-symbol-ts-parameter-fg-color: #e36209
44+
--doc-symbol-ts-project-fg-color: #24292f
45+
--doc-symbol-ts-property-fg-color: #6f42c1
46+
--doc-symbol-ts-type-fg-color: #6f42c1
47+
--doc-symbol-ts-type_alias-fg-color: #6f42c1
48+
--doc-symbol-ts-variable-fg-color: #e36209
49+
50+
--doc-symbol-ts-accessor-bg-color: #6f42c11a
51+
--doc-symbol-ts-attribute-bg-color: #6f42c11a
52+
--doc-symbol-ts-class-bg-color: #22863a1a
53+
--doc-symbol-ts-constructor-bg-color: #1f66ff1a
54+
--doc-symbol-ts-data-bg-color: #0366d61a
55+
--doc-symbol-ts-enum-bg-color: #6f42c11a
56+
--doc-symbol-ts-enum_member-bg-color: #f0ad4e1a
57+
--doc-symbol-ts-interface-bg-color: #6f42c11a
58+
--doc-symbol-ts-method-bg-color: #0366d61a
59+
--doc-symbol-ts-module-bg-color: #0366d61a
60+
--doc-symbol-ts-namespace-bg-color: #0366d61a
61+
--doc-symbol-ts-parameter-bg-color: #e362091a
62+
--doc-symbol-ts-project-bg-color: #24292f1a
63+
--doc-symbol-ts-property-bg-color: #6f42c11a
64+
--doc-symbol-ts-type-bg-color: #6f42c11a
65+
--doc-symbol-ts-type_alias-bg-color: #6f42c11a
66+
--doc-symbol-ts-variable-bg-color: #e362091a
4167
}
4268

4369
[data-md-color-scheme="slate"] {
44-
--doc-symbol-data-fg-color: #46c2cb;
45-
46-
--doc-symbol-data-bg-color: #46c2cb1a;
70+
--doc-symbol-ts-accessor-fg-color: #d4a5f0
71+
--doc-symbol-ts-attribute-fg-color: #d4a5f0
72+
--doc-symbol-ts-class-fg-color: #78e7d1
73+
--doc-symbol-ts-constructor-fg-color: #6ba3ff
74+
--doc-symbol-ts-data-fg-color: #58a6ff
75+
--doc-symbol-ts-enum-fg-color: #d4a5f0
76+
--doc-symbol-ts-enum_member-fg-color: #ffb864
77+
--doc-symbol-ts-interface-fg-color: #d4a5f0
78+
--doc-symbol-ts-method-fg-color: #58a6ff
79+
--doc-symbol-ts-module-fg-color: #58a6ff
80+
--doc-symbol-ts-namespace-fg-color: #58a6ff
81+
--doc-symbol-ts-parameter-fg-color: #f4a261
82+
--doc-symbol-ts-project-fg-color: #e1e4e8
83+
--doc-symbol-ts-property-fg-color: #d4a5f0
84+
--doc-symbol-ts-type-fg-color: #d4a5f0
85+
--doc-symbol-ts-type_alias-fg-color: #d4a5f0
86+
--doc-symbol-ts-variable-fg-color: #f4a261
87+
88+
--doc-symbol-ts-accessor-bg-color: #d4a5f01a
89+
--doc-symbol-ts-attribute-bg-color: #d4a5f01a
90+
--doc-symbol-ts-class-bg-color: #78e7d11a
91+
--doc-symbol-ts-constructor-bg-color: #6ba3ff1a
92+
--doc-symbol-ts-data-bg-color: #58a6ff1a
93+
--doc-symbol-ts-enum-bg-color: #d4a5f01a
94+
--doc-symbol-ts-enum_member-bg-color: #ffb8641a
95+
--doc-symbol-ts-interface-bg-color: #d4a5f01a
96+
--doc-symbol-ts-method-bg-color: #58a6ff1a
97+
--doc-symbol-ts-module-bg-color: #58a6ff1a
98+
--doc-symbol-ts-namespace-bg-color: #58a6ff1a
99+
--doc-symbol-ts-parameter-bg-color: #f4a2611a
100+
--doc-symbol-ts-project-bg-color: #e1e4e81a
101+
--doc-symbol-ts-property-bg-color: #d4a5f01a
102+
--doc-symbol-ts-type-bg-color: #d4a5f01a
103+
--doc-symbol-ts-type_alias-bg-color: #d4a5f01a
104+
--doc-symbol-ts-variable-bg-color: #f4a2611a
47105
}
48106
```
49107

50-
The `[data-md-color-scheme="*"]` selectors work with the [Material for MkDocs] theme.
51-
If you are using another theme, adapt the selectors to this theme
52-
if it supports light and dark themes,
53-
otherwise just override the variables at root level:
108+
The `[data-md-color-scheme="*"]` selectors work with the [Material for MkDocs] theme. If you are using another theme, adapt the selectors to this theme if it supports light and dark themes, otherwise just override the variables at root level:
54109

55110
```css title="docs/css/mkdocstrings.css"
56111
:root {
57-
--doc-symbol-data-fg-color: #d1b619;
58-
59-
--doc-symbol-data-bg-color: #d1b6191a;
112+
--doc-symbol-ts-data-fg-color: #d1b619;
113+
--doc-symbol-ts-data-bg-color: #d1b6191a;
60114
}
61115
```
62116

@@ -66,32 +120,29 @@ otherwise just override the variables at root level:
66120
<div id="preview-symbol-colors">
67121
<style>
68122
[data-md-color-scheme="default"] #preview-symbol-colors {
69-
--doc-symbol-data-fg-color: #d1b619;
70-
71-
--doc-symbol-data-bg-color: #d1b6191a;
123+
--doc-symbol-ts-data-fg-color: #d1b619;
124+
--doc-symbol-ts-data-bg-color: #d1b6191a;
72125
}
73126

74127
[data-md-color-scheme="slate"] #preview-symbol-colors {
75-
--doc-symbol-data-fg-color: #46c2cb;
76-
77-
--doc-symbol-data-bg-color: #46c2cb1a;
128+
--doc-symbol-ts-data-fg-color: #46c2cb;
129+
--doc-symbol-ts-data-bg-color: #46c2cb1a;
78130
}
79131
</style>
80132
<p>
81133
Try cycling through the themes to see the colors for each theme:
82-
<code class="doc-symbol doc-symbol-data"></code
134+
<code class="doc-symbol doc-symbol-ts-data"></code
83135
</p>
84136
</div>
85137

86138
///
87139

88140
### Names
89141

90-
You can also change the actual symbol names.
91-
For example, to use single letters instead of truncated types:
142+
You can also change the actual symbol names. For example, to use single letters instead of truncated types:
92143

93144
```css title="docs/css/mkdocstrings.css"
94-
.doc-symbol-data::after {
145+
.doc-symbol-ts-data::after {
95146
content: "D";
96147
}
97148
```
@@ -101,12 +152,12 @@ For example, to use single letters instead of truncated types:
101152

102153
<div id="preview-symbol-names">
103154
<style>
104-
#preview-symbol-names .doc-symbol-data::after {
155+
#preview-symbol-names .doc-symbol-ts-data::after {
105156
content: "D";
106157
}
107158
</style>
108159
<ul>
109-
<li>Data: <code class="doc-symbol doc-symbol-data"></code></li>
160+
<li>Data: <code class="doc-symbol doc-symbol-ts-data"></code></li>
110161
</ul>
111162
</div>
112163

0 commit comments

Comments
 (0)