8000 feat: Release Insiders features of the $500/month funding goal · romain-intel/mkdocstrings-python@2a11b40 · GitHub
[go: up one dir, main page]
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
F438
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)
0