CHANGELOG.md

@@ -5,6 +5,23 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- insertion marker -->
+## [1.8.0](https://github.com/mkdocstrings/python/releases/tag/1.8.0) - 2024-01-08
+
+<small>[Compare with 1.7.5](https://github.com/mkdocstrings/python/compare/1.7.5...1.8.0)</small>
+
+### Features
+
+- Release Insiders features of the $500/month funding goal ([bd30106](https://github.com/mkdocstrings/python/commit/bd301061fe9c647f9b91c2c9b4baa784c304eca7) by Timothée Mazzucotelli).
+    The features and projects related to *mkdocstrings-python* are:
+
+    - [Cross-references for type annotations in signatures](https://mkdocstrings.github.io/python/usage/configuration/signatures/#signature_crossrefs)
+    - [Symbol types in headings and table of contents](https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_toc)
+    - [`griffe-inherited-docstrings`](https://mkdocstrings.github.io/griffe-inherited-docstrings/), a Griffe extension for inheriting docstrings
+    - [`griffe2md`](https://mkdocstrings.github.io/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.7.5](https://github.com/mkdocstrings/python/releases/tag/1.7.5) - 2023-11-21
 
 <small>[Compare with 1.7.4](https://github.com/mkdocstrings/python/compare/1.7.4...1.7.5)</small>

docs/insiders/changelog.md

@@ -1,3 +1,51 @@
 # Changelog
 
 ## mkdocstrings-python Insiders
+
+### 1.5.1 <small>September 12, 2023</small> { id="1.5.1" }
+
+- Prevent empty auto-summarized Methods section.
+
+### 1.5.0 <small>September 05, 2023</small> { id="1.5.0" }
+
+- Render function signature overloads.
+
+### 1.4.0 <small>August 27, 2023</small> { id="1.4.0" }
+
+- Render cross-references in attribute signatures.
+
+### 1.3.0 <small>August 24, 2023</small> { id="1.3.0" }
+
+- Add "method" symbol type.
+
+### 1.2.0 <small>August 20, 2023</small> { id="1.2.0" }
+
+- Add [member auto-summaries](../usage/configuration/members.md#summary).
+
+### 1.1.4 <small>July 17, 2023</small> { id="1.1.4" }
+
+- Fix heading level increment for class members.
+
+### 1.1.3 <small>July 17, 2023</small> { id="1.1.3" }
+
+- Fix heading level (avoid with clause preventing to decrease it).
+
+### 1.1.2 <small>July 15, 2023</small> { id="1.1.2" }
+
+- Use non-breaking spaces after symbol types.
+
+### 1.1.1 <small>June 27, 2023</small> { id="1.1.1" }
+
+- Correctly escape expressions in signatures and other rendered types.
+
+### 1.1.0 <small>June 4, 2023</small> { id="1.1.0" }
+
+- Add [Symbol types in headings and table of contents](../usage/configuration/headings.md#show_symbol_type_toc).
+
+### 1.0.0 <small>May 10, 2023</small> { id="1.0.0" }
+
+- Add [cross-references for type annotations in signatures](../usage/configuration/signatures.md#signature_crossrefs).
+    Make sure to update your local templates as the signature of the
+    [`format_signature` filter][mkdocstrings_handlers.python.rendering.do_format_signature]
+    has changed. The templates that must be updated:
+    `class.html`, `expression.html`, `function.html` and `signature.html`.

docs/insiders/goals.yml

@@ -1 +1,18 @@
-goals: {}
+goals:
+  500:
+    name: PlasmaVac User Guide
+    features:
+    - name: Cross-references for type annotations in signatures
+      ref: /usage/configuration/signatures/#signature_crossrefs
+      since: 2023/05/10
+    - name: Symbol types in headings and table of contents
+      ref: /usage/configuration/headings/#show_symbol_type_toc
+      since: 2023/06/04
+  1000:
+    name: GraviFridge User Manual
+    features:
+    - name: Auto-summary of object members
+      ref: /usage/configuration/members/#summary
+      since: 2023/08/20
+    - name: Automatic rendering of function signature overloads
+      since: 2023/09/05

docs/insiders/index.md

@@ -33,7 +33,6 @@ Sponsorships start as low as [**$10 a month**][sponsors].[^2]
     technical reasons. Such contributions are still very much welcome as
     they help ensuring the project's sustainability.
 
-
 ## What sponsorships achieve
 
 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]
     you can be sure that bugs are fixed quickly and new features are added
     regularly.
 
-<!-- If you're unsure if you should sponsor this project, check out the list of
+If you're unsure if you should sponsor this project, check out the list of
 [completed funding goals][goals completed] to learn whether you're already using features that
-were developed with the help of sponsorships. You're most likely using at least
-a handful of them, [thanks to our awesome sponsors][sponsors]! -->
+were developed with the help of sponsorships.
+<!-- You're most likely using at least a handful of them,
+[thanks to our awesome sponsors][sponsors]! -->
 
 ## What's in it for me?
 
 ```python exec="1" session="insiders"
-data_source = "docs/insiders/goals.yml"
+data_source = [
+    "docs/insiders/goals.yml",
+    ("griffe-inherited-docstrings", "https://mkdocstrings.github.io/griffe-inherited-docstrings/", "insiders/goals.yml"),
+    ("griffe-pydantic", "https://mkdocstrings.github.io/griffe-pydantic/", "insiders/goals.yml"),
+    ("griffe-typing-deprecated", "https://mkdocstrings.github.io/griffe-typing-deprecated/", "insiders/goals.yml"),
+]
 ```
 
 <!-- blacken-docs:off -->

docs/insiders/installation.md

@@ -28,15 +28,15 @@ and [how to use it](https://pawamoy.github.io/pypi-insiders/#usage).
 *mkdocstrings-python Insiders* can be installed with `pip` [using SSH][using ssh]:
 
 ```bash
-pip install git+ssh://git@github.com/pawamoy-insiders/python.git
+pip install git+ssh://git@github.com/pawamoy-insiders/mkdocstrings-python.git
 ```
 
   [using ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
 
 Or using HTTPS:
 
 ```bash
-pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/python.git
+pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/mkdocstrings-python.git
 ```
 
 >? NOTE: **How to get a GitHub personal access token**  
@@ -82,7 +82,7 @@ with [Twine]:
   [Artifactory]: https://jfrog.com/help/r/jfrog-artifactory-documentation/pypi-repositories
   [Google Cloud]: https://cloud.google.com/artifact-registry/docs/python
   [pypiserver]: https://pypi.org/project/pypiserver/
-  [Github Releases]: https://github.com/pawamoy-insiders/python/releases
+  [Github Releases]: https://github.com/pawamoy-insiders/mkdocstrings-python/releases
   [Twine]: https://pypi.org/project/twine/
 
 ```bash
@@ -142,7 +142,7 @@ as it is against our [Terms of use](index.md#terms).**
 >
 > ```bash
 > # clone the repository
-> git clone git@github.com:pawamoy-insiders/python
+> git clone git@github.com:pawamoy-insiders/mkdocstrings-python
 > cd python
 >
 > # install build
@@ -178,7 +178,7 @@ as it is against our [Terms of use](index.md#terms).**
 Of course, you can use *mkdocstrings-python Insiders* directly from `git`:
 
 ```
-git clone git@github.com:pawamoy-insiders/python
+git clone git@github.com:pawamoy-insiders/mkdocstrings-python
 ```
 
 When cloning from `git`, the package must be installed:

docs/schema.json

@@ -108,6 +108,18 @@
               "type": "boolean",
               "default": false
             },
+            "show_symbol_type_heading": {
+              "title": "Show the symbol type in headings (e.g. mod, class, func and attr).",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_heading",
+              "type": "boolean",
+              "default": false
+            },
+            "show_symbol_type_toc": {
+              "title": "Show the symbol type in the Table of Contents (e.g. mod, class, func and attr).",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_toc",
+              "type": "boolean",
+              "default": false
+            },
             "show_category_heading": {
               "title": "When grouped by categories, show a heading for each category.",
               "markdownDescription": "https://mkdocstrings.github.io/python/usage/configuration/headings/#show_category_heading",

docs/usage/configuration/headings.md

@@ -387,3 +387,131 @@ plugins:
 <p>Docstring of the method.</p>
 ////
 ///
+
+## `show_symbol_type_heading`
+
+[:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Show the symbol type in headings.
+
+This option will prefix headings with
+<code class="doc-symbol doc-symbol-attribute"></code>,
+<code class="doc-symbol doc-symbol-function"></code>,
+<code class="doc-symbol doc-symbol-method"></code>,
+<code class="doc-symbol doc-symbol-class"></code> or
+<code class="doc-symbol doc-symbol-module"></code> types.
+See also [`show_symbol_type_toc`][show_symbol_type_toc].
+
+To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_symbol_type_heading: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: package.module
+    options:
+      show_symbol_type_heading: false
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With symbol type in headings
+<h1><code class="doc-symbol doc-symbol-module"></code> <code>module</code></h1>
+<p>Docstring of the module.</p>
+<h2><code class="doc-symbol doc-symbol-attribute"></code> <code>attribute</code></h2>
+<p>Docstring of the module attribute.</p>
+<h2><code class="doc-symbol doc-symbol-function"></code> <code>function</code></h2>
+<p>Docstring of the function.</p>
+<h2><code class="doc-symbol doc-symbol-class"></code> <code>Class</code></h2>
+<p>Docstring of the class.</p>
+<h3><code class="doc-symbol doc-symbol-method"></code> <code>method</code></h3>
+<p>Docstring of the method.</p>
+////
+
+//// tab | Without symbol type in headings
+<h1><code>module</code></h1>
+<p>Docstring of the module.</p>
+<h2><code>attribute</code></h2>
+<p>Docstring of the module attribute.</p>
+<h2><code>function</code></h2>
+<p>Docstring of the function.</p>
+<h2><code>Class</code></h2>
+<p>Docstring of the class.</p>
+<h3><code>method</code></h3>
+<p>Docstring of the method.</p>
+////
+///
+
+## `show_symbol_type_toc`
+
+[:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Show the symbol type in the Table of Contents.
+
+This option will prefix items in the ToC with
+<code class="doc-symbol doc-symbol-attribute"></code>,
+<code class="doc-symbol doc-symbol-function"></code>,
+<code class="doc-symbol doc-symbol-method"></code>,
+<code class="doc-symbol doc-symbol-class"></code> or
+<code class="doc-symbol doc-symbol-module"></code> types.
+See also [`show_symbol_type_heading`][show_symbol_type_heading].
+
+To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_symbol_type_toc: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: package.module
+    options:
+      show_symbol_type_toc: false
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With symbol type in ToC
+<ul style="list-style: none;">
+  <li><code class="doc-symbol doc-symbol-module"></code> module</li>
+  <li><code class="doc-symbol doc-symbol-attribute"></code> attribute</li>
+  <li><code class="doc-symbol doc-symbol-function"></code> function</li>
+  <li><code class="doc-symbol doc-symbol-class"></code> Class
+    <ul style="list-style: none;">
+      <li><code class="doc-symbol doc-symbol-method"></code> method</li>
+    </ul>
+  </li>
+</ul>
+////
+
+//// tab | Without symbol type in ToC
+<ul style="list-style: none;">
+  <li>module</li>
+  <li>attribute</li>
+  <li>function</li>
+  <li>Class
+    <ul style="list-style: none;">
+      <li>method</li>
+    </ul>
+  </li>
+</ul>
+////
+///