Skip to content

Commit b58b601

Browse files
pawamoypawamoy
committed
clean up
1 parent aa40d2d commit b58b601

File tree

3 files changed

+160
-163
lines changed

3 files changed

+160
-163
lines changed

‎docs/snippets/package/__init__.py‎

Lines changed: 0 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
from importlib import metadata
2-
from typing import Iterator, TypeVar
32

43
def get_version(dist: str = "mkdocstrings-python") -> str:
54
"""Get version of the given distribution.
@@ -18,40 +17,3 @@ def get_version(dist: str = "mkdocstrings-python") -> str:
1817

1918
current_version: str = get_version(dist="mkdocstrings-python")
2019
"""Current package version."""
21-
22-
23-
class MagicBag[T: (str, bytes) = str](list[T]):
24-
"""A magic bag of items.
25-
26-
Type parameters:
27-
T: Some type.
28-
"""
29-
30-
def __init__[U: (int, bool)](self, *args: T, flag1: U | None = None, flag2: U | None = None) -> None:
31-
"""Initialize bag.
32-
33-
Type parameters:
34-
U: Some flag type.
35-
36-
Parameters:
37-
flag1: Some flag.
38-
flag2: Some flag.
39-
"""
40-
super().__init__(args)
41-
self.flag1 = flag1
42-
self.flag2 = flag2
43-
44-
def mutate[K](self, item: T, into: K) -> K:
45-
"""Shake the bag to mutate an item into something else (and eject it).
46-
47-
Type parameters:
48-
K: Some other type.
49-
50-
Parameters:
51-
item: The item to mutate.
52-
into: Mutate the item into something like this.
53-
54-
Returns:
55-
The mutated item.
56-
"""
57-
...

‎docs/snippets/package/generics.py‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
class MagicBag[T: (str, bytes) = str](list[T]):
2+
"""A magic bag of items.
3+
4+
Type parameters:
5+
T: Some type.
6+
"""
7+
8+
def __init__[U: (int, bool)](self, *args: T, flag1: U | None = None, flag2: U | None = None) -> None:
9+
"""Initialize bag.
10+
11+
Type parameters:
12+
U: Some flag type.
13+
14+
Parameters:
15+
flag1: Some flag.
16+
flag2: Some flag.
17+
"""
18+
super().__init__(args)
19+
self.flag1 = flag1
20+
self.flag2 = flag2
21+
22+
def mutate[K](self, item: T, into: K) -> K:
23+
"""Shake the bag to mutate an item into something else (and eject it).
24+
25+
Type parameters:
26+
K: Some other type.
27+
28+
Parameters:
29+
item: The item to mutate.
30+
into: Mutate the item into something like this.
31+
32+
Returns:
33+
The mutated item.
34+
"""
35+
...

‎docs/usage/configuration/headings.md‎

Lines changed: 125 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -197,131 +197,6 @@ To customize symbols, see [Customizing symbol types](../customization.md/#symbol
197197

198198
///
199199

200-
[](){#option-type_parameter_headings}
201-
## `type_parameter_headings`
202-
203-
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
204-
205-
Whether to render headings for generic class, function/method and type alias
206-
type parameters.
207-
208-
With this option enabled, each type parameter of a generic object (including
209-
type parameters of `__init__` methods merged in their parent class with the
210-
[`merge_init_into_class`][] option) gets a permalink, an entry in the Table of
211-
Contents, and an entry in the generated objects inventory. The permalink and
212-
inventory entry allow cross-references from internal and external pages.
213-
214-
The identifier used in the permalink and inventory is of the following form:
215-
`path.to.function:type_param_name`. To manually cross-reference a parameter,
216-
you can therefore use this Markdown syntax:
217-
218-
```md
219-
- Class type parameter: [`Param`][package.module.Class[Param\]]
220-
- Method type parameter: [`Param`][package.module.Class.method[Param\]]
221-
- Function type parameter: [`Param`][package.module.function[Param\]]
222-
- Type alias type parameter: [`Param`][package.module.TypeAlias[Param\]]
223-
- Type variable tuple: [`*Args`][package.module.function[*Args\]]
224-
- Parameter specification: [`**Params`][package.module.function[**Params\]]
225-
```
226-
227-
Enabling this option along with [`signature_crossrefs`][] will automatically
228-
render cross-references to type parameters in class/function/method/type alias
229-
signatures.
230-
231-
```yaml title="in mkdocs.yml (global configuration)"
232-
plugins:
233-
- mkdocstrings:
234-
handlers:
235-
python:
236-
options:
237-
type_parameter_headings: false
238-
```
239-
240-
```md title="or in docs/some_page.md (local configuration)"
241-
::: path.to.module
242-
options:
243-
type_parameter_headings: true
244-
```
245-
246-
/// admonition | Preview: Cross-references
247-
type: preview
248-
249-
```md exec="on"
250-
::: package.MagicBag
251-
options:
252-
heading_level: 3
253-
docstring_section_style: list
254-
show_bases: true
255-
summary: false
256-
separate_signature: true
257-
show_signature_type_parameters: true
258-
type_parameter_headings: true
259-
```
260-
261-
///
262-
263-
/// admonition | Preview: Type parameter sections
264-
type: preview
265-
266-
//// tab | Table style
267-
```md exec="on"
268-
::: package.MagicBag
269-
options:
270-
members: false
271-
heading_level: 3
272-
show_root_heading: false
273-
show_root_toc_entry: false
274-
parameter_headings: true
275-
docstring_section_style: table
276-
show_docstring_description: false
277-
show_docstring_parameters: false
278-
show_docstring_returns: false
279-
```
280-
////
281-
282-
//// tab | List style
283-
```md exec="on"
284-
::: package.MagicBag
285-
options:
286-
members: false
287-
heading_level: 3
288-
show_root_heading: false
289-
show_root_toc_entry: false
290-
parameter_headings: true
291-
docstring_section_style: list
292-
show_docstring_description: false
293-
show_docstring_parameters: false
294-
show_docstring_returns: false
295-
```
296-
////
297-
298-
//// tab | Spacy style
299-
```md exec="on"
300-
::: package.MagicBag
301-
options:
302-
members: false
303-
heading_level: 3
304-
show_root_heading: false
305-
show_root_toc_entry: false
306-
parameter_headings: true
307-
docstring_section_style: spacy
308-
show_docstring_description: false
309-
show_docstring_parameters: false
310-
show_docstring_returns: false
311-
```
312-
////
313-
///
314-
315-
/// admonition | Preview: Table of contents (with symbol types)
316-
type: preview
317-
318-
<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> mutate<br>
319-
<code class="doc-symbol doc-symbol-toc doc-symbol-type_parameter" style="margin-left: 16px;"></code> U
320-
321-
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
322-
323-
///
324-
325200
[](){#option-show_root_heading}
326201
## `show_root_heading`
327202

@@ -807,3 +682,128 @@ NOTE: **Use with/without `heading`.** If you use this option without specifying
807682
heading: "My fancy module"
808683
toc_label: "My fancy module"
809684
```
685+
686+
[](){#option-type_parameter_headings}
687+
## `type_parameter_headings`
688+
689+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
690+
691+
Whether to render headings for generic class, function/method and type alias
692+
type parameters.
693+
694+
With this option enabled, each type parameter of a generic object (including
695+
type parameters of `__init__` methods merged in their parent class with the
696+
[`merge_init_into_class`][] option) gets a permalink, an entry in the Table of
697+
Contents, and an entry in the generated objects inventory. The permalink and
698+
inventory entry allow cross-references from internal and external pages.
699+
700+
The identifier used in the permalink and inventory is of the following form:
701+
`path.to.function:type_param_name`. To manually cross-reference a parameter,
702+
you can therefore use this Markdown syntax:
703+
704+
```md
705+
- Class type parameter: [`Param`][package.module.Class[Param\]]
706+
- Method type parameter: [`Param`][package.module.Class.method[Param\]]
707+
- Function type parameter: [`Param`][package.module.function[Param\]]
708+
- Type alias type parameter: [`Param`][package.module.TypeAlias[Param\]]
709+
- Type variable tuple: [`*Args`][package.module.function[*Args\]]
710+
- Parameter specification: [`**Params`][package.module.function[**Params\]]
711+
```
712+
713+
Enabling this option along with [`signature_crossrefs`][] will automatically
714+
render cross-references to type parameters in class/function/method/type alias
715+
signatures.
716+
717+
```yaml title="in mkdocs.yml (global configuration)"
718+
plugins:
719+
- mkdocstrings:
720+
handlers:
721+
python:
722+
options:
723+
type_parameter_headings: false
724+
```
725+
726+
```md title="or in docs/some_page.md (local configuration)"
727+
::: path.to.module
728+
options:
729+
type_parameter_headings: true
730+
```
731+
732+
/// admonition | Preview: Cross-references
733+
type: preview
734+
735+
```md exec="on"
736+
::: package.generics.MagicBag
737+
options:
738+
heading_level: 3
739+
docstring_section_style: list
740+
show_bases: true
741+
summary: false
742+
separate_signature: true
743+
show_signature_type_parameters: true
744+
type_parameter_headings: true
745+
```
746+
747+
///
748+
749+
/// admonition | Preview: Type parameter sections
750+
type: preview
751+
752+
//// tab | Table style
753+
```md exec="on"
754+
::: package.generics.MagicBag
755+
options:
756+
members: false
757+
heading_level: 3
758+
show_root_heading: false
759+
show_root_toc_entry: false
760+
parameter_headings: true
761+
docstring_section_style: table
762+
show_docstring_description: false
763+
show_docstring_parameters: false
764+
show_docstring_returns: false
765+
```
766+
////
767+
768+
//// tab | List style
769+
```md exec="on"
770+
::: package.generics.MagicBag
771+
options:
772+
members: false
773+
heading_level: 3
774+
show_root_heading: false
775+
show_root_toc_entry: false
776+
parameter_headings: true
777+
docstring_section_style: list
778+
show_docstring_description: false
779+
show_docstring_parameters: false
780+
show_docstring_returns: false
781+
```
782+
////
783+
784+
//// tab | Spacy style
785+
```md exec="on"
786+
::: package.generics.MagicBag
787+
options:
788+
members: false
789+
heading_level: 3
790+
show_root_heading: false
791+
show_root_toc_entry: false
792+
parameter_headings: true
793+
docstring_section_style: spacy
794+
show_docstring_description: false
795+
show_docstring_parameters: false
796+
show_docstring_returns: false
797+
```
798+
////
799+
///
800+
801+
/// admonition | Preview: Table of contents (with symbol types)
802+
type: preview
803+
804+
<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> mutate<br>
805+
<code class="doc-symbol doc-symbol-toc doc-symbol-type_parameter" style="margin-left: 16px;"></code> U
806+
807+
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
808+
809+
///

0 commit comments

Comments
 (0)