Skip to content

Commit 2a11b40

Browse files
pawamoypawamoy
committed
feat: Release Insiders features of the $500/month funding goal
The features and projects related to *mkdocstrings* are: - Cross-references for type annotations in signatures - Symbol types in headings and table of contents - `griffe-inherited-docstrings`, a Griffe extension for inheriting docstrings - `griffe2md`, a tool to output API docs to Markdown using Griffe See the complete list of features and projects here: https://pawamoy.github.io/insiders/#500-plasmavac-user-guide.
1 parent ff7e8c5 commit 2a11b40

32 files changed

+862
-99
lines changed

‎docs/insiders/changelog.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,51 @@
11
# Changelog
22

33
## mkdocstrings-python Insiders
4+
5+
### 1.5.1 <small>September 12, 2023</small> { id="1.5.1" }
6+
7+
- Prevent empty auto-summarized Methods section.
8+
9+
### 1.5.0 <small>September 05, 2023</small> { id="1.5.0" }
10+
11+
- Render function signature overloads.
12+
13+
### 1.4.0 <small>August 27, 2023</small> { id="1.4.0" }
14+
15+
- Render cross-references in attribute signatures.
16+
17+
### 1.3.0 <small>August 24, 2023</small> { id="1.3.0" }
18+
19+
- Add "method" symbol type.
20+
21+
### 1.2.0 <small>August 20, 2023</small> { id="1.2.0" }
22+
23+
- Add [member auto-summaries](../usage/configuration/members.md#summary).
24+
25+
### 1.1.4 <small>July 17, 2023</small> { id="1.1.4" }
26+
27+
- Fix heading level increment for class members.
28+
29+
### 1.1.3 <small>July 17, 2023</small> { id="1.1.3" }
30+
31+
- Fix heading level (avoid with clause preventing to decrease it).
32+
33+
### 1.1.2 <small>July 15, 2023</small> { id="1.1.2" }
34+
35+
- Use non-breaking spaces after symbol types.
36+
37+
### 1.1.1 <small>June 27, 2023</small> { id="1.1.1" }
38+
39+
- Correctly escape expressions in signatures and other rendered types.
40+
41+
### 1.1.0 <small>June 4, 2023</small> { id="1.1.0" }
42+
43+
- Add [Symbol types in headings and table of contents](../usage/configuration/headings.md#show_symbol_type_toc).
44+
45+
### 1.0.0 <small>May 10, 2023</small> { id="1.0.0" }
46+
47+
- Add [cross-references for type annotations in signatures](../usage/configuration/signatures.md#signature_crossrefs).
48+
Make sure to update your local templates as the signature of the
49+
[`format_signature` filter][mkdocstrings_handlers.python.rendering.do_format_signature]
50+
has changed. The templates that must be updated:
51+
`class.html`, `expression.html`, `function.html` and `signature.html`.

‎docs/insiders/goals.yml

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,18 @@
1-
goals: {}
1+
goals:
2+
500:
3+
name: PlasmaVac User Guide
4+
features:
5+
- name: Cross-references for type annotations in signatures
6+
ref: /usage/configuration/signatures/#signature_crossrefs
7+
since: 2023/05/10
8+
- name: Symbol types in headings and table of contents
9+
ref: /usage/configuration/headings/#show_symbol_type_toc
10+
since: 2023/06/04
11+
1000:
12+
name: GraviFridge User Manual
13+
features:
14+
- name: Auto-summary of object members
15+
ref: /usage/configuration/members/#summary
16+
since: 2023/08/20
17+
- name: Automatic rendering of function signature overloads
18+
since: 2023/09/05

‎docs/insiders/index.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@ Sponsorships start as low as [**$10 a month**][sponsors].[^2]
3333
technical reasons. Such contributions are still very much welcome as
3434
they help ensuring the project's sustainability.
3535

36-
3736
## What sponsorships achieve
3837

3938
Sponsorships make this project sustainable, as they buy the maintainers of this
@@ -48,15 +47,21 @@ The biggest bottleneck in Open Source is time.[^3]
4847
you can be sure that bugs are fixed quickly and new features are added
4948
regularly.
5049

51-
<!-- If you're unsure if you should sponsor this project, check out the list of
50+
If you're unsure if you should sponsor this project, check out the list of
5251
[completed funding goals][goals completed] to learn whether you're already using features that
53-
were developed with the help of sponsorships. You're most likely using at least
54-
a handful of them, [thanks to our awesome sponsors][sponsors]! -->
52+
were developed with the help of sponsorships.
53+
<!-- You're most likely using at least a handful of them,
54+
[thanks to our awesome sponsors][sponsors]! -->
5555

5656
## What's in it for me?
5757

5858
```python exec="1" session="insiders"
59-
data_source = "docs/insiders/goals.yml"
59+
data_source = [
60+
"docs/insiders/goals.yml",
61+
("griffe-inherited-docstrings", "https://mkdocstrings.github.io/griffe-inherited-docstrings/", "insiders/goals.yml"),
62+
("griffe-pydantic", "https://mkdocstrings.github.io/griffe-pydantic/", "insiders/goals.yml"),
63+
("griffe-typing-deprecated", "https://mkdocstrings.github.io/griffe-typing-deprecated/", "insiders/goals.yml"),
64+
]
6065
```
6166

6267
<!-- blacken-docs:off -->

‎docs/insiders/installation.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,15 @@ and [how to use it](https://pawamoy.github.io/pypi-insiders/#usage).
2828
*mkdocstrings-python Insiders* can be installed with `pip` [using SSH][using ssh]:
2929

3030
```bash
31-
pip install git+ssh://git@github.com/pawamoy-insiders/python.git
31+
pip install git+ssh://git@github.com/pawamoy-insiders/mkdocstrings-python.git
3232
```
3333

3434
[using ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
3535

3636
Or using HTTPS:
3737

3838
```bash
39-
pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/python.git
39+
pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/mkdocstrings-python.git
4040
```
4141

4242
>? NOTE: **How to get a GitHub personal access token**
@@ -82,7 +82,7 @@ with [Twine]:
8282
[Artifactory]: https://jfrog.com/help/r/jfrog-artifactory-documentation/pypi-repositories
8383
[Google Cloud]: https://cloud.google.com/artifact-registry/docs/python
8484
[pypiserver]: https://pypi.org/project/pypiserver/
85-
[Github Releases]: https://github.com/pawamoy-insiders/python/releases
85+
[Github Releases]: https://github.com/pawamoy-insiders/mkdocstrings-python/releases
8686
[Twine]: https://pypi.org/project/twine/
8787

8888
```bash
@@ -142,7 +142,7 @@ as it is against our [Terms of use](index.md#terms).**
142142
>
143143
> ```bash
144144
> # clone the repository
145-
> git clone git@github.com:pawamoy-insiders/python
145+
> git clone git@github.com:pawamoy-insiders/mkdocstrings-python
146146
> cd python
147147
>
148148
> # install build
@@ -178,7 +178,7 @@ as it is against our [Terms of use](index.md#terms).**
178178
Of course, you can use *mkdocstrings-python Insiders* directly from `git`:
179179
180180
```
181-
git clone git@github.com:pawamoy-insiders/python
181+
git clone git@github.com:pawamoy-insiders/mkdocstrings-python
182182
```
183183
184184
When cloning from `git`, the package must be installed:

‎docs/schema.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,18 @@
108108
"type": "boolean",
109109
"default": false
110110
},
111+
"show_symbol_type_heading": {
112+
"title": "Show the symbol type in headings (e.g. mod, class, func and attr).",
113+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_heading",
114+
"type": "boolean",
115+
"default": false
116+
},
117+
"show_symbol_type_toc": {
118+
"title": "Show the symbol type in the Table of Contents (e.g. mod, class, func and attr).",
119+
"markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_toc",
120+
"type": "boolean",
121+
"default": false
122+
},
111123
"show_category_heading": {
112124
"title": "When grouped by categories, show a heading for each category.",
113125
"markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_category_heading",

‎docs/usage/configuration/headings.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -387,3 +387,131 @@ plugins:
387387
<p>Docstring of the method.</p>
388388
////
389389
///
390+
391+
## `show_symbol_type_heading`
392+
393+
[:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)
394+
395+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
396+
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
397+
398+
Show the symbol type in headings.
399+
400+
This option will prefix headings with
401+
<code class="doc-symbol doc-symbol-attribute"></code>,
402+
<code class="doc-symbol doc-symbol-function"></code>,
403+
<code class="doc-symbol doc-symbol-method"></code>,
404+
<code class="doc-symbol doc-symbol-class"></code> or
405+
<code class="doc-symbol doc-symbol-module"></code> types.
406+
See also [`show_symbol_type_toc`][show_symbol_type_toc].
407+
408+
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
409+
410+
```yaml title="in mkdocs.yml (global configuration)"
411+
plugins:
412+
- mkdocstrings:
413+
handlers:
414+
python:
415+
options:
416+
show_symbol_type_heading: true
417+
```
418+
419+
```md title="or in docs/some_page.md (local configuration)"
420+
::: package.module
421+
options:
422+
show_symbol_type_heading: false
423+
```
424+
425+
/// admonition | Preview
426+
type: preview
427+
428+
//// tab | With symbol type in headings
429+
<h1><code class="doc-symbol doc-symbol-module"></code> <code>module</code></h1>
430+
<p>Docstring of the module.</p>
431+
<h2><code class="doc-symbol doc-symbol-attribute"></code> <code>attribute</code></h2>
432+
<p>Docstring of the module attribute.</p>
433+
<h2><code class="doc-symbol doc-symbol-function"></code> <code>function</code></h2>
434+
<p>Docstring of the function.</p>
435+
<h2><code class="doc-symbol doc-symbol-class"></code> <code>Class</code></h2>
436+
<p>Docstring of the class.</p>
437+
<h3><code class="doc-symbol doc-symbol-method"></code> <code>method</code></h3>
438+
<p>Docstring of the method.</p>
439+
////
440+
441+
//// tab | Without symbol type in headings
442+
<h1><code>module</code></h1>
443+
<p>Docstring of the module.</p>
444+
<h2><code>attribute</code></h2>
445+
<p>Docstring of the module attribute.</p>
446+
<h2><code>function</code></h2>
447+
<p>Docstring of the function.</p>
448+
<h2><code>Class</code></h2>
449+
<p>Docstring of the class.</p>
450+
<h3><code>method</code></h3>
451+
<p>Docstring of the method.</p>
452+
////
453+
///
454+
455+
## `show_symbol_type_toc`
456+
457+
[:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)
458+
459+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
460+
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
461+
462+
Show the symbol type in the Table of Contents.
463+
464+
This option will prefix items in the ToC with
465+
<code class="doc-symbol doc-symbol-attribute"></code>,
466+
<code class="doc-symbol doc-symbol-function"></code>,
467+
<code class="doc-symbol doc-symbol-method"></code>,
468+
<code class="doc-symbol doc-symbol-class"></code> or
469+
<code class="doc-symbol doc-symbol-module"></code> types.
470+
See also [`show_symbol_type_heading`][show_symbol_type_heading].
471+
472+
To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
473+
474+
```yaml title="in mkdocs.yml (global configuration)"
475+
plugins:
476+
- mkdocstrings:
477+
handlers:
478+
python:
479+
options:
480+
show_symbol_type_toc: true
481+
```
482+
483+
```md title="or in docs/some_page.md (local configuration)"
484+
::: package.module
485+
options:
486+
show_symbol_type_toc: false
487+
```
488+
489+
/// admonition | Preview
490+
type: preview
491+
492+
//// tab | With symbol type in ToC
493+
<ul style="list-style: none;">
494+
<li><code class="doc-symbol doc-symbol-module"></code> module</li>
495+
<li><code class="doc-symbol doc-symbol-attribute"></code> attribute</li>
496+
<li><code class="doc-symbol doc-symbol-function"></code> function</li>
497+
<li><code class="doc-symbol doc-symbol-class"></code> Class
498+
<ul style="list-style: none;">
499+
<li><code class="doc-symbol doc-symbol-method"></code> method</li>
500+
</ul>
501+
</li>
502+
</ul>
503+
////
504+
505+
//// tab | Without symbol type in ToC
506+
<ul style="list-style: none;">
507+
<li>module</li>
508+
<li>attribute</li>
509+
<li>function</li>
510+
<li>Class
511+
<ul style="list-style: none;">
512+
<li>method</li>
513+
</ul>
514+
</li>
515+
</ul>
516+
////
517+
///

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy