Skip to content

Commit 8cdcca3

Browse files
pawamoypawamoy
committed
docs: Update docs
1 parent fc3dfc6 commit 8cdcca3

6 files changed

Lines changed: 67 additions & 107 deletions

File tree

‎docs/usage/configuration/general.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,10 @@ plugins:
2020
```
2121
2222
```md title="in docs/some_page.md (local configuration)"
23-
::: your_package.your_module.your_func
23+
::: src/hello.h
2424
options:
2525
extra:
2626
foo: bar
2727
```
2828
29-
...will inject both `hello` and `foo` into the Jinja context when rendering `your_package.your_module.your_func`.
29+
...will inject both `hello` and `foo` into the Jinja context when rendering `src/hello.h`.

‎docs/usage/configuration/headings.md‎

Lines changed: 29 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@ A custom string to use as the heading of the root object (i.e. the object specif
1010
WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object.
1111

1212
```md title="in docs/some_page.md (local configuration)"
13-
::: path.to.module
13+
::: src/hello.h
1414
options:
15-
heading: "My fancy module"
15+
heading: "My fancy code"
1616
```
1717

1818
[](){ #option-heading_level }
@@ -39,37 +39,11 @@ plugins:
3939
```
4040
4141
```md title="or in docs/some_page.md (local configuration)"
42-
::: path.to.module
42+
::: src/hello.h
4343
options:
4444
heading_level: 3
4545
```
4646
47-
/// admonition | Preview
48-
type: preview
49-
50-
//// tab | With level 3 and root heading
51-
<h3><code>module</code> (3)</h3>
52-
<p>Docstring of the module.</p>
53-
<h4><code>ClassA</code> (4)</h4>
54-
<p>Docstring of class A.</p>
55-
<h4><code>ClassB</code> (4)</h4>
56-
<p>Docstring of class B.</p>
57-
<h5><code>method_1</code> (5)</h5>
58-
<p>Docstring of the method.</p>
59-
////
60-
61-
//// tab | With level 3, without root heading
62-
<p>Docstring of the module.</p>
63-
<h3><code>ClassA</code> (3)</h3>
64-
<p>Docstring of class A.</p>
65-
<h3><code>ClassB</code> (3)</h3>
66-
<p>Docstring of class B.</p>
67-
<h4><code>method_1</code> (4)</h4>
68-
<p>Docstring of the method.</p>
69-
////
70-
///
71-
72-
7347
[](){ #option-show_symbol_type_heading }
7448
## `show_symbol_type_heading`
7549

@@ -78,11 +52,10 @@ plugins:
7852
Show the symbol type in headings.
7953

8054
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.
55+
<code class="doc-symbol doc-symbol-c-function"></code>,
56+
<code class="doc-symbol doc-symbol-c-var"></code>,
57+
<code class="doc-symbol doc-symbol-c-macro"></code> or
58+
<code class="doc-symbol doc-symbol-c-typedef"></code> types.
8659
See also [`show_symbol_type_toc`][show_symbol_type_toc].
8760

8861
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
@@ -97,7 +70,7 @@ plugins:
9770
```
9871

9972
```md title="or in docs/some_page.md (local configuration)"
100-
::: package.module
73+
::: src/hello.h
10174
options:
10275
show_symbol_type_heading: false
10376
```
@@ -106,29 +79,17 @@ plugins:
10679
type: preview
10780

10881
//// 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>
82+
<h2><code class="doc-symbol doc-symbol-c-function"></code> <code>function</code></h2><p>Docstring of the function.</p>
83+
<h2><code class="doc-symbol doc-symbol-c-var"></code> <code>var</code></h2><p>Docstring of the var.</p>
84+
<h2><code class="doc-symbol doc-symbol-c-macro"></code> <code>macro</code></h2><p>Docstring of the macro.</p>
85+
<h2><code class="doc-symbol doc-symbol-c-typedef"></code> <code>typedef</code></h2><p>Docstring of the typedef.</p>
11986
////
12087

12188
//// 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>
89+
<h2><code>function</code></h2><p>Docstring of the function.</p>
90+
<h2><code>var</code></h2><p>Docstring of the var.</p>
91+
<h2><code>macro</code></h2><p>Docstring of the macro.</p>
92+
<h2><code>typedef</code></h2><p>Docstring of the typedef.</p>
13293
////
13394
///
13495

@@ -140,11 +101,10 @@ plugins:
140101
Show the symbol type in the Table of Contents.
141102

142103
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.
104+
<code class="doc-symbol doc-symbol-c-function"></code>,
105+
<code class="doc-symbol doc-symbol-c-var"></code>,
106+
<code class="doc-symbol doc-symbol-c-macro"></code> or
107+
<code class="doc-symbol doc-symbol-c-typedef"></code> types.
148108
See also [`show_symbol_type_heading`][show_symbol_type_heading].
149109

150110
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
@@ -159,7 +119,7 @@ plugins:
159119
```
160120

161121
```md title="or in docs/some_page.md (local configuration)"
162-
::: package.module
122+
::: src/hello.h
163123
options:
164124
show_symbol_type_toc: false
165125
```
@@ -169,27 +129,19 @@ plugins:
169129

170130
//// tab | With symbol type in ToC
171131
<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>
132+
<li><code class="doc-symbol doc-symbol-c-function"></code> function</li>
133+
<li><code class="doc-symbol doc-symbol-c-var"></code> var</li>
134+
<li><code class="doc-symbol doc-symbol-c-macro"></code> macro</li>
135+
<li><code class="doc-symbol doc-symbol-c-typedef"></code> typedef</li>
180136
</ul>
181137
////
182138

183139
//// tab | Without symbol type in ToC
184140
<ul style="list-style: none;">
185-
<li>module</li>
186-
<li>attribute</li>
187141
<li>function</li>
188-
<li>Class
189-
<ul style="list-style: none;">
190-
<li>method</li>
191-
</ul>
192-
</li>
142+
<li>var</li>
143+
<li>macro</li>
144+
<li>typedef</li>
193145
</ul>
194146
////
195147
///
@@ -206,7 +158,7 @@ WARNING: **Not advised to be used as a global configuration option.** This optio
206158
NOTE: **Use with/without `heading`.** If you use this option without specifying a custom `heading`, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for `heading` and `toc_label`, we leave the customization entirely up to you.
207159

208160
```md title="in docs/some_page.md (local configuration)"
209-
::: path.to.module
161+
::: src/hello.h
210162
options:
211163
heading: "My fancy module"
212164
toc_label: "My fancy module"

‎docs/usage/configuration/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,15 @@ For example, globally:
1010
plugins:
1111
- mkdocstrings:
1212
handlers:
13-
python:
13+
c:
1414
options:
1515
do_something: true
1616
```
1717
1818
...and locally, overriding the global configuration:
1919
2020
```md title="docs/some_page.md"
21-
::: package.module.class
21+
::: src/hello.h
2222
options:
2323
do_something: false
2424
```

‎docs/usage/customization.md‎

Lines changed: 34 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -35,15 +35,27 @@ by overriding the values of our CSS variables, for example:
3535

3636
```css title="docs/css/mkdocstrings.css"
3737
[data-md-color-scheme="default"] {
38-
--doc-symbol-data-fg-color: #d1b619;
39-
40-
--doc-symbol-data-bg-color: #d1b6191a;
38+
--doc-symbol-c-function-fg-color: #8250df;
39+
--doc-symbol-c-var-fg-color: #953800;
40+
--doc-symbol-c-macro-fg-color: #5cad0f;
41+
--doc-symbol-c-typedef-fg-color: #0550ae;
42+
43+
--doc-symbol-c-function-bg-color: #8250df1a;
44+
--doc-symbol-c-var-bg-color: #9538001a;
45+
--doc-symbol-c-macro-bg-color: #5cad0f1a;
46+
--doc-symbol-c-typedef-bg-color: #0550ae1a;
4147
}
4248

4349
[data-md-color-scheme="slate"] {
44-
--doc-symbol-data-fg-color: #46c2cb;
45-
46-
--doc-symbol-data-bg-color: #46c2cb1a;
50+
--doc-symbol-c-function-fg-color: #d2a8ff;
51+
--doc-symbol-c-var-fg-color: #ffa657;
52+
--doc-symbol-c-macro-fg-color: #baff79;
53+
--doc-symbol-c-typedef-fg-color: #79c0ff;
54+
55+
--doc-symbol-c-function-bg-color: #d2a8ff1a;
56+
--doc-symbol-c-var-bg-color: #ffa6571a;
57+
--doc-symbol-c-macro-bg-color: #baff791a;
58+
--doc-symbol-c-typedef-bg-color: #79c0ff1a;
4759
}
4860
```
4961

@@ -54,32 +66,29 @@ otherwise just override the variables at root level:
5466

5567
```css title="docs/css/mkdocstrings.css"
5668
:root {
57-
--doc-symbol-data-fg-color: #d1b619;
58-
59-
--doc-symbol-data-bg-color: #d1b6191a;
69+
--doc-symbol-c-function-fg-color: #d1b619;
70+
--doc-symbol-c-function-bg-color: #d1b6191a;
6071
}
6172
```
6273

6374
/// admonition | Preview
6475
type: preview
6576

66-
<div id="preview-symbol-colors">
77+
<div id="preview-symbol-c-colors">
6778
<style>
68-
[data-md-color-scheme="default"] #preview-symbol-colors {
69-
--doc-symbol-data-fg-color: #d1b619;
70-
71-
--doc-symbol-data-bg-color: #d1b6191a;
79+
[data-md-color-scheme="default"] #preview-symbol-c-colors {
80+
--doc-symbol-c-function-fg-color: #d1b619;
81+
--doc-symbol-c-function-bg-color: #d1b6191a;
7282
}
7383

74-
[data-md-color-scheme="slate"] #preview-symbol-colors {
75-
--doc-symbol-data-fg-color: #46c2cb;
76-
77-
--doc-symbol-data-bg-color: #46c2cb1a;
84+
[data-md-color-scheme="slate"] #preview-symbol-c-colors {
85+
--doc-symbol-c-function-fg-color: #46c2cb;
86+
--doc-symbol-c-function-bg-color: #46c2cb1a;
7887
}
7988
</style>
8089
<p>
8190
Try cycling through the themes to see the colors for each theme:
82-
<code class="doc-symbol doc-symbol-data"></code
91+
<code class="doc-symbol doc-symbol-c-function"></code
8392
</p>
8493
</div>
8594

@@ -91,22 +100,22 @@ You can also change the actual symbol names.
91100
For example, to use single letters instead of truncated types:
92101

93102
```css title="docs/css/mkdocstrings.css"
94-
.doc-symbol-data::after {
95-
content: "D";
103+
.doc-symbol-c-function::after {
104+
content: "F";
96105
}
97106
```
98107

99108
/// admonition | Preview
100109
type: preview
101110

102-
<div id="preview-symbol-names">
111+
<div id="preview-symbol-c-names">
103112
<style>
104-
#preview-symbol-names .doc-symbol-data::after {
105-
content: "D";
113+
#preview-symbol-c-names .doc-symbol-c-function::after {
114+
content: "F";
106115
}
107116
</style>
108117
<ul>
109-
<li>Data: <code class="doc-symbol doc-symbol-data"></code></li>
118+
<li>Function: <code class="doc-symbol doc-symbol-c-function"></code></li>
110119
</ul>
111120
</div>
112121

‎docs/usage/index.md‎

Whitespace-only changes.

‎mkdocs.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@ nav:
2020
- Credits: credits.md
2121
- License: license.md
2222
- Usage:
23-
- usage/index.md
2423
- Configuration:
2524
- usage/configuration/index.md
2625
- General: usage/configuration/general.md

0 commit comments

Comments
 (0)