docs: Lint

pawamoy · pawamoy · commit 4da5cc570535 · 2025-08-11T13:31:18.000+02:00
diff --git a/docs/code-of-conduct.md b/docs/code-of-conduct.md
@@ -1 +1,5 @@
+---
+title: Code of Conduct
+---
+
 --8<-- "CODE_OF_CONDUCT.md"
diff --git a/docs/community.md b/docs/community.md
@@ -4,7 +4,7 @@ Griffe is part of is the [mkdocstrings](https://mkdocstrings.github.io/) ecosyst
 
 You can start new discussions on GitHub, in the following repositories, depending on the specificity of the discussion: [griffe](https://github.com/mkdocstrings/griffe), [mkdocstrings-python](https://github.com/mkdocstrings/python), [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings), and [MkDocs](https://github.com/mkdocs/mkdocs).
 
-You can also join our dedicated Gitter channels: [Griffe channel](https://app.gitter.im/#/room/#mkdocstrings_griffe:gitter.im){ target="_blank" }, [mkdocstrings-python channel](https://app.gitter.im/#/room/#mkdocstrings_python:gitter.im){ target="_blank" }, [mkdocstrings channel](https://app.gitter.im/#/room/#mkdocstrings_community:gitter.im){ target="_blank" }, and [MkDocs channel](https://app.gitter.im/#/room/#mkdocs_community:gitter.im){ target="_blank" }. 
+You can also join our dedicated Gitter channels: [Griffe channel](https://app.gitter.im/#/room/#mkdocstrings_griffe:gitter.im){ target="_blank" }, [mkdocstrings-python channel](https://app.gitter.im/#/room/#mkdocstrings_python:gitter.im){ target="_blank" }, [mkdocstrings channel](https://app.gitter.im/#/room/#mkdocstrings_community:gitter.im){ target="_blank" }, and [MkDocs channel](https://app.gitter.im/#/room/#mkdocs_community:gitter.im){ target="_blank" }.
 
 The best place to share about Griffe is of course our Gitter channel.
 
diff --git a/docs/extensions/official.md b/docs/extensions/official.md
@@ -5,11 +5,11 @@ Official extensions are developed and maintained within the mkdocstrings organiz
 Extension | Description | Sponsors only?
 --------- | ----------- | --------------
 [`autodocstringstyle`](official/autodocstringstyle.md) | Set docstring style to `auto` for external packages. | [:octicons-heart-fill-24:{ .pulse }](../insiders/index.md){ .insiders }
-[`inherited-docstrings`](official/inherited-docstrings.md) | Inherit docstrings from parent classes.
+ [`inherited-docstrings`](official/inherited-docstrings.md) | Inherit docstrings from parent classes. |
 [`public-redundant-aliases`](official/public-redundant-aliases.md) | Mark objects imported with redundant aliases as public. | [:octicons-heart-fill-24:{ .pulse }](../insiders/index.md){ .insiders }
 [`public-wildcard-imports`](official/public-wildcard-imports.md) | Mark wildcard imported objects as public. | [:octicons-heart-fill-24:{ .pulse }](../insiders/index.md){ .insiders }
-[`pydantic`](official/pydantic.md) | Support for [Pydantic](https://docs.pydantic.dev/latest/) models.
+ [`pydantic`](official/pydantic.md) | Support for [Pydantic](https://docs.pydantic.dev/latest/) models. |
 [`runtime-objects`](official/runtime-objects.md) | Access runtime objects corresponding to each loaded Griffe object through their `extra` attribute. | [:octicons-heart-fill-24:{ .pulse }](../insiders/index.md){ .insiders }
 [`sphinx`](official/sphinx.md) | Parse [Sphinx](https://www.sphinx-doc.org/)-comments above attributes (`#:`) as docstrings. | [:octicons-heart-fill-24:{ .pulse }](../insiders/index.md){ .insiders }
-[`typing-doc`](official/typingdoc.md) | Support for [PEP 727](https://peps.python.org/pep-0727/)'s [`typing.Doc`][typing_extensions.Doc], "Documentation in Annotated Metadata".
-[`warnings-deprecated`](official/warnings-deprecated.md) | Support for [PEP 702](https://peps.python.org/pep-0702/)'s [`warnings.deprecated`][], "Marking deprecations using the type system".
+ [`typing-doc`](official/typingdoc.md) | Support for [PEP 727](https://peps.python.org/pep-0727/)'s [`typing.Doc`][typing_extensions.Doc], "Documentation in Annotated Metadata". |
+ [`warnings-deprecated`](official/warnings-deprecated.md) | Support for [PEP 702](https://peps.python.org/pep-0702/)'s [`warnings.deprecated`][], "Marking deprecations using the type system". |
diff --git a/docs/guide/contributors/architecture.md b/docs/guide/contributors/architecture.md
@@ -110,7 +110,7 @@ The test suite is based on [pytest](https://docs.pytest.org/en/8.2.x/). Test mod
 
 The internal API is contained within the `src/griffe/_internal` folder. The top-level `griffe/__init__.py` module exposes all the public API, by importing the internal objects from various submodules of `griffe._internal`.
 
-Users then import `griffe` directly, or import objects from it. 
+Users then import `griffe` directly, or import objects from it.
 
 We'll be honest: our code organization is not the most elegant, but it works :shrug: Have a look at the following module dependency graph, which will basically tell you nothing except that we have a lot of inter-module dependencies. Arrows read as "imports from". The code base is generally pleasant to work with though.
 
diff --git a/docs/guide/contributors/commands.md b/docs/guide/contributors/commands.md
@@ -14,6 +14,7 @@ $ make
 Commands are always available: they don't require any Python dependency to be installed.
 
 [](){#command-setup}
+
 ### `setup`
 
 ::: make.setup
@@ -25,6 +26,7 @@ Commands are always available: they don't require any Python dependency to be in
         parameter_headings: false
 
 [](){#command-help}
+
 ### `help`
 
 ::: make.help
@@ -36,6 +38,7 @@ Commands are always available: they don't require any Python dependency to be in
         parameter_headings: false
 
 [](){#command-run}
+
 ### `run`
 
 ::: make.run
@@ -47,6 +50,7 @@ Commands are always available: they don't require any Python dependency to be in
         parameter_headings: false
 
 [](){#command-multirun}
+
 ### `multirun`
 
 ::: make.multirun
@@ -58,6 +62,7 @@ Commands are always available: they don't require any Python dependency to be in
         parameter_headings: false
 
 [](){#command-allrun}
+
 ### `allrun`
 
 ::: make.allrun
@@ -69,6 +74,7 @@ Commands are always available: they don't require any Python dependency to be in
         parameter_headings: false
 
 [](){#command-3.x}
+
 ### `3.x`
 
 ::: make.run3x
@@ -80,6 +86,7 @@ Commands are always available: they don't require any Python dependency to be in
         parameter_headings: false
 
 [](){#command-clean}
+
 ### `clean`
 
 ::: make.clean
@@ -91,6 +98,7 @@ Commands are always available: they don't require any Python dependency to be in
         parameter_headings: false
 
 [](){#command-vscode}
+
 ### `vscode`
 
 ::: make.vscode
@@ -112,6 +120,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
 - `make 3.x duty TASK`, to run a task on a specific Python version
 
 [](){#task-build}
+
 ### `build`
 
 ::: duties.build
@@ -123,6 +132,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-changelog}
+
 ### `changelog`
 
 ::: duties.changelog
@@ -134,6 +144,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-check}
+
 ### `check`
 
 ::: duties.check
@@ -145,6 +156,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-check-api}
+
 ### `check-api`
 
 ::: duties.check_api
@@ -156,6 +168,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-check-docs}
+
 ### `check-docs`
 
 ::: duties.check_docs
@@ -167,6 +180,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-check-quality}
+
 ### `check-quality`
 
 ::: duties.check_quality
@@ -178,6 +192,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-check-types}
+
 ### `check-types`
 
 ::: duties.check_types
@@ -189,6 +204,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-coverage}
+
 ### `coverage`
 
 ::: duties.coverage
@@ -200,6 +216,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-docs}
+
 ### `docs`
 
 ::: duties.docs
@@ -211,6 +228,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-docs-deploy}
+
 ### `docs-deploy`
 
 ::: duties.docs_deploy
@@ -222,6 +240,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-format}
+
 ### `format`
 
 ::: duties.format
@@ -233,6 +252,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-fuzz}
+
 ### `fuzz`
 
 ::: duties.fuzz
@@ -244,6 +264,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-publish}
+
 ### `publish`
 
 ::: duties.publish
@@ -255,6 +276,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-release}
+
 ### `release`
 
 ::: duties.release
@@ -266,6 +288,7 @@ Tasks require the Python dependencies to be installed. They use various tools an
         parameter_headings: false
 
 [](){#task-test}
+
 ### `test`
 
 ::: duties.test
diff --git a/docs/guide/contributors/workflow.md b/docs/guide/contributors/workflow.md
@@ -79,15 +79,15 @@ If you are unsure about how to deprecate something or mark legacy code, let us d
 
 Commit messages must follow our convention based on the [Angular style](https://gist.github.com/stephenparish/9941e89d80e2bc58a153#format-of-the-commit-message) or the [Karma convention](https://karma-runner.github.io/4.0/dev/git-commit-msg.html):
 
-```
+```text
 type(scope): Subject
 
 Body.
 ```
 
 **Subject and body must be valid Markdown.** Subject must have proper casing (uppercase for first letter if it makes sense), but no dot at the end, and no punctuation in general. Example:
 
-```
+```text
 feat: Add CLI option to run in verbose mode
 ```
 
@@ -107,7 +107,7 @@ Scope and body are optional. Type can be:
 
 If you write a body, please add trailers at the end (for example issues and PR references, or co-authors), without relying on GitHub's flavored Markdown:
 
-```
+```text
 This is the body of the commit message.
 
 Issue-10: https://github.com/namespace/project/issues/10
diff --git a/docs/guide/users/checking.md b/docs/guide/users/checking.md
@@ -108,10 +108,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    
+
     # Griffe requires that Git tags are available.
     - run: git fetch --depth=1 --tags
-    
+
     - uses: actions/setup-python@v5
       with:
         python-version: "3.11"
@@ -644,6 +644,7 @@ NOTE: Unless inherited members are lost in the process, removing a class base is
 Griffe supports writing detected breakages in multiple formats, or styles.
 
 [](){#format-oneline}
+
 ### One-line
 
 - **CLI**: `-f oneline` / no flags
@@ -657,6 +658,7 @@ $ griffe check griffe -ssrc -b0.46.0 -a0.45.0
 ```
 
 [](){#format-verbose}
+
 ### Verbose
 
 - **CLI**: `-f verbose` / `-v`
@@ -670,6 +672,7 @@ $ griffe check griffe -ssrc -b0.46.0 -a0.45.0 --verbose
 ```
 
 [](){#format-markdown}
+
 ### Markdown
 
 [:octicons-tag-24: Insiders 1.0.0](../../insiders/changelog.md#1.0.0)
@@ -703,6 +706,7 @@ The Markdown format is adapted for changelogs. It doesn't show the file and line
 ```
 
 [](){#format-github}
+
 ### GitHub
 
 [:octicons-tag-24: Insiders 1.0.0](../../insiders/changelog.md#1.0.0)
diff --git a/docs/guide/users/extending.md b/docs/guide/users/extending.md
@@ -674,7 +674,6 @@ See [how to use extensions](#using-extensions) to learn more about how to load a
 [^5]: Now `ExceptHandler`, in the `handlers` attribute of `Try` nodes.
 [^6]: Now a list of expressions in the `finalbody` attribute of `Try` nodes.
 
-
 ## Next steps
 
 Extensions are a powerful mechanism to customize or enhance the data loaded by Griffe. But sometimes, all you need to do to improve the data is to make Griffe happy by following a few conventions. We therefore invite you to read our recommendations on [public APIs](recommendations/public-apis.md), [Python code best practices](recommendations/python-code.md) and [docstrings](recommendations/docstrings.md).
diff --git a/docs/guide/users/how-to/set-docstring-styles.md b/docs/guide/users/how-to/set-docstring-styles.md
@@ -37,7 +37,7 @@ Depending on the markup you use in docstrings, you can add a comment that tells
         """
     ```
 
-Your Griffe extension can then use regular expressions to search for such comments. For example with Markdown (HTML) comments: 
+Your Griffe extension can then use regular expressions to search for such comments. For example with Markdown (HTML) comments:
 
 ```python
 import re
diff --git a/docs/guide/users/recommendations/docstrings.md b/docs/guide/users/recommendations/docstrings.md
@@ -188,7 +188,7 @@ class Ghost:
 
     def wander(self) -> None:
         """Wander the earth.
-        
+
         That's it, really.
 
         Examples:
@@ -252,7 +252,7 @@ def yield_athletes(quantity: int) -> Iterator[Ghost]:
 
     Parameters:
         quantity: How many ghost athletes you want.
-    
+
     Yields:
         Ghost athletes. They're just regular ghosts.
     """
diff --git a/docs/guide/users/recommendations/python-code.md b/docs/guide/users/recommendations/python-code.md
@@ -363,7 +363,7 @@ struct MyClass {
 
 Some modules of the standard library are guilty of this too, and do so inconsistently (`ast` and `_ast`, `io` and `_io`, depending on the Python version...). For this reason, when checking if an object was declared in the currently inspected module, Griffe ultimately considers that any qualified name is equal to itself with each component stripped from leading underscores:
 
-```
+```python
 a.b.c == _a.b.c
 a.b.c == _a._b._c
 a.__b._c == __a.b.c
diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md
@@ -3,21 +3,25 @@
 ## Griffe Insiders
 
 [](){#insiders-1.3.0}
+
 ### 1.3.0 <small>August 09, 2024</small> { id="1.3.0" }
 
 - [Automatic docstring style detection](../reference/docstrings.md#auto-style)
 
 [](){#insiders-1.2.0}
+
 ### 1.2.0 <small>March 11, 2024</small> { id="1.2.0" }
 
 - [Expressions modernization](../guide/users/navigating.md#modernization)
 
 [](){#insiders-1.1.0}
+
 ### 1.1.0 <small>March 02, 2024</small> { id="1.1.0" }
 
 - Check API of Python packages by [downloading them from PyPI](../guide/users/checking.md#using-pypi)
 
 [](){#insiders-1.0.0}
+
 ### 1.0.0 <small>January 16, 2024</small> { id="1.0.0" }
 
 - Add [Markdown][markdown] and [GitHub][github] output formats to the check command
diff --git a/docs/insiders/index.md b/docs/insiders/index.md
@@ -87,7 +87,6 @@ You can cancel your sponsorship anytime.[^5]
 
 [^5]: If you cancel your sponsorship, GitHub schedules a cancellation request which will become effective at the end of the billing cycle. This means that even though you cancel your sponsorship, you will keep your access to Insiders as long as your cancellation isn't effective. All charges are processed by GitHub through Stripe. As we don't receive any information regarding your payment, and GitHub doesn't offer refunds, sponsorships are non-refundable.
 
-
 [:octicons-heart-fill-24:{ .pulse } &nbsp; Join our <span id="sponsors-count"></span> awesome sponsors][github sponsor profile]{ .md-button .md-button--primary }
 
 <hr>
diff --git a/docs/insiders/installation.md b/docs/insiders/installation.md
@@ -41,13 +41,13 @@ pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/griffe.git
 
 Of course, you can use *Griffe Insiders* directly using Git:
 
-```
+```sh
 git clone git@github.com:pawamoy-insiders/griffe
 ```
 
 When cloning with Git, the package must be installed:
 
-```
+```sh
 pip install -e griffe
 ```
 
diff --git a/docs/license.md b/docs/license.md
@@ -6,6 +6,6 @@ hide:
 
 # License
 
-```
+```text
 --8<-- "LICENSE"
 ```
diff --git a/docs/reference/docstrings.md b/docs/reference/docstrings.md

-Original file line number
+Diff line change
@@ @@ -1 +1,5 @@ @@
 +---
 +title: Code of Conduct
 +---
++
 --8<-- "CODE_OF_CONDUCT.md"