Merge branch 'main' into feat/allow-custom-headings-and-labels

Author: pawamoy

CHANGELOG.md

@@ -227,12 +227,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - 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.
 
@@ -464,7 +464,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
     You can see how to use the filter in this commit's changes:
     [f686f4e4](https://github.com/mkdocstrings/python/commit/f686f4e4599cea64686d4ef4863b507dd096a513).
-    
+
 **We take this as an opportunity to go out of beta and bump the version to 1.0.0.
 This will allow users to rely on semantic versioning.**
 

config/pytest.ini

@@ -12,6 +12,4 @@ filterwarnings =
   error
   # TODO: remove once pytest-xdist 4 is released
   ignore:.*rsyncdir:DeprecationWarning:xdist
-  # TODO: remove once Griffe releases v1
-  ignore:.*`get_logger`:DeprecationWarning:_griffe
-  ignore:.*`name`:DeprecationWarning:_griffe
+  ignore:.*fallback anchor function:DeprecationWarning:mkdocstrings

docs/.glossary.md

@@ -6,7 +6,7 @@
 [Griffe]: https://github.com/mkdocstrings/griffe
 [ReadTheDocs Sphinx theme]: https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html
 [Spacy's documentation]: https://spacy.io/api/doc/
-[Black]: https://pypi.org/project/black/ 
+[Black]: https://pypi.org/project/black/
 [Material for MkDocs]: https://squidfunk.github.io/mkdocs-material
 [Ruff]: https://docs.astral.sh/ruff
 

docs/.overrides/main.html

@@ -1,13 +1,13 @@
 {% extends "base.html" %}
 
 {% block announce %}
-  
+
     <strong>Fund this project</strong> through
     <a href="{{ 'insiders/#how-to-become-a-sponsor' | url }}"><strong>sponsorship</strong></a>
     <span class="twemoji heart pulse">
       {% include ".icons/octicons/heart-fill-16.svg" %}
     </span> &mdash;
-  
+
   Follow
   <strong>@pawamoy</strong> on
   <a rel="me" href="https://fosstodon.org/@pawamoy">

docs/.overrides/partials/comments.html

@@ -31,7 +31,7 @@ <h2 id="__comments">Feedback</h2>
                 : "light"
 
             // Instruct Giscus to set theme
-            giscus.setAttribute("data-theme", theme) 
+            giscus.setAttribute("data-theme", theme)
         }
 
         // Register event handlers after documented loaded

docs/insiders/index.md

@@ -161,7 +161,7 @@ You can cancel your sponsorship anytime.[^5]
 
 The following section lists all funding goals. Each goal contains a list of
 features prefixed with a checkmark symbol, denoting whether a feature is
-:octicons-check-circle-fill-24:{ style="color: #00e676" } already available or 
+:octicons-check-circle-fill-24:{ style="color: #00e676" } already available or
 :octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned,
 but not yet implemented. When the funding goal is hit,
 the features are released for general availability.
@@ -221,7 +221,7 @@ by the [ISC License][license]. However, we kindly ask you to respect our
 
 - Please **don't distribute the source code** of Insiders. You may freely use
   it for public, private or commercial projects, privately fork or mirror it,
-  but please don't make the source code public, as it would counteract the 
+  but please don't make the source code public, as it would counteract the
   sponsorware strategy.
 
 - If you cancel your subscription, you're automatically removed as a

docs/insiders/installation.md

@@ -42,21 +42,21 @@ Or using HTTPS:
 pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/mkdocstrings-python.git
 ```
 
->? NOTE: **How to get a GitHub personal access token**  
+>? NOTE: **How to get a GitHub personal access token?**
 > The `GH_TOKEN` environment variable is a GitHub token.
 > It can be obtained by creating a [personal access token] for
 > your GitHub account. It will give you access to the Insiders repository,
 > programmatically, from the command line or GitHub Actions workflows:
-> 
+>
 > 1.  Go to https://github.com/settings/tokens
 > 2.  Click on [Generate a new token]
 > 3.  Enter a name and select the [`repo`][scopes] scope
 > 4.  Generate the token and store it in a safe place
-> 
+>
 >   [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
 >   [Generate a new token]: https://github.com/settings/tokens/new
 >   [scopes]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
-> 
+>
 > Note that the personal access
 > token must be kept secret at all times, as it allows the owner to access your
 > private repositories.

docs/usage/configuration/general.md

@@ -55,6 +55,30 @@ plugins:
 ////
 ///
 
+## `force_inspection`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
+
+Whether to force inspecting modules (importing them) even if their source code is available.
+
+This option is useful when you know that dynamic analysis (inspection) yields better results than static analysis. Do not use this blindly: the recommended approach is to write a Griffe extension that will improve extracted API data. See [How to selectively inspect objects](https://mkdocstrings.github.io/griffe/guide/users/how-to/selectively-inspect/).
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          force_inspection: false
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.object
+    options:
+      force_inspection: true
+```
+
 ## `show_bases`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -250,7 +274,7 @@ plugins:
 ::: your_package.your_module
     options:
       preload_modules:
-      - their_package   
+      - their_package
 ```
 
 ```python title="your_package/your_module.py"

docs/usage/configuration/headings.md

@@ -490,7 +490,7 @@ When [grouped by categories][group_by_category], show a heading for each categor
 These category headings will appear in the table of contents,
 allowing you to link to them using their permalinks.
 
-WARNING: **Not recommended with deeply nested object**
+WARNING: **Not recommended with deeply nested objects.**
 When injecting documentation for deeply nested objects,
 you'll quickly run out of heading levels, and the objects
 at the bottom of the tree risk all getting documented

docs/usage/configuration/signatures.md

@@ -202,7 +202,7 @@ plugins:
 
 [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
 [:octicons-tag-24: Insiders 1.8.0](../../insiders/changelog.md#1.8.0) —
-**This feature also requires 
+**This feature also requires
 [Griffe Insiders](https://mkdocstrings.github.io/griffe/insiders/)
 to be installed.**