docs: Light grammar tidying in documentation

lmmx · web-flow · commit 971773927cba · 2025-02-14T23:53:59.000+01:00
PR-360: #360
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -8,8 +8,8 @@ There are multiple ways to contribute to this project:
 - with **bug reports**: only you (the users) can help us find and fix bugs! We greatly appreciate if you can give us a bit of your time to create a proper [bug report](https://github.com/mkdocstrings/griffe/issues/new?assignees=pawamoy&labels=unconfirmed&projects=&template=bug_report.md&title=bug%3A+) on our issue tracker. Same as for feature requests, make sure the bug is not already reported, by searching through issues first.
 - with **user support**: watch activity on the [Github repository](https://github.com/mkdocstrings/griffe) and our [Gitter channel](https://app.gitter.im/#/room/#mkdocstrings_griffe:gitter.im){ target="_blank" } to answer issues and discussions created by users. Answering questions from users can take a lot of time off maintenance and new features: helping us with user support means more time for us to work on the project.
 - with **documentation**: spotted a mistake in the documentation? Found a paragraph unclear or a section missing? Reporting those already helps a lot, and if you can, sending pull requests is even better.
-- with **code**: if you are interested in a feature request, or are experiencing a reported bug, you can contribute a feature or a fix. You can simply drop a comment in the relevant issue, and we will do our best to guide you.
+- with **code**: if you are interested in a feature request, or are experiencing a reported bug, you can contribute a feature or a fix. You can simply drop a comment on the relevant issue, and we will do our best to guide you.
 
-For easy documentation fixes, you can edit a file and send a pull request [directly from the GitHub web interface](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files#editing-files-in-another-users-repository). For more complex fixes or improvements, please read our contributor guide. The guide will show you how to setup a development environment to run tests or serve the documentation locally.
+For easy documentation fixes, you can edit a file and send a pull request [directly from the GitHub web interface](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files#editing-files-in-another-users-repository). For more complex fixes or improvements, please read our contributor guide. The guide will show you how to set up a development environment to run tests or serve the documentation locally.
 
 [:fontawesome-solid-helmet-safety: Contributor guide](guide/contributors.md){ .md-button }
diff --git a/docs/extensions/official.md b/docs/extensions/official.md
@@ -1,6 +1,6 @@
 # Official extensions
 
-Official extensions are developed and maintained within the mkdocstrings organization on GitHub, in separated repositories. They generally bring support for various third-party libraries or other documentation-related features that are part of Python's standard library.
+Official extensions are developed and maintained within the mkdocstrings organization on GitHub, in separate repositories. They generally bring support for various third-party libraries or other documentation-related features that are part of Python's standard library.
 
 Extension | Description | Sponsors only?
 --------- | ----------- | --------------
diff --git a/docs/extensions/official/inherited-docstrings.md b/docs/extensions/official/inherited-docstrings.md
@@ -7,7 +7,7 @@
 
 ---
 
-This extension, when enabled, iterates on the declared members of all classes found within a package, and if they don't have a docstring, but have a parent member with a docstring, sets their docstring to this parent docstring.
+This extension, when enabled, iterates over the declared members of all classes found within a package, and if they don't have a docstring, but do have a parent member with a docstring, sets their docstring to that parent's docstring.
 
 ```python
 class Base:
@@ -25,4 +25,4 @@ class Derived(Base):
         ...
 ```
 
-Following with example, *without* the extension `Derived.attr` and `Derived.hello` have no docstrings, while *with* the extension they will have the `Base.attr` and `Base.hello` docstrings attached, respectively.
+In the example above, *without* the extension `Derived.attr` and `Derived.hello` have no docstrings, while *with* the extension they will have the `Base.attr` and `Base.hello` docstrings attached, respectively.
diff --git a/docs/extensions/official/public-redundant-aliases.md b/docs/extensions/official/public-redundant-aliases.md
@@ -9,4 +9,4 @@
 
 ---
 
-This extension marks every objects that was imported with a redundant alias as public. See our documentation on the [redundant aliases convention](../../guide/users/recommendations/public-apis.md#redundant-aliases).
+This extension marks every object that was imported with a redundant alias as public. See our documentation on the [redundant aliases convention](../../guide/users/recommendations/public-apis.md#redundant-aliases).
diff --git a/docs/extensions/official/public-wildcard-imports.md b/docs/extensions/official/public-wildcard-imports.md
@@ -9,4 +9,4 @@
 
 ---
 
-This extension marks every objects that was imported with a wildcard import as public. See our documentation on the [wildcard imports convention](../../guide/users/recommendations/public-apis.md#wildcard-imports).
+This extension marks every object that was imported with a wildcard import as public. See our documentation on the [wildcard imports convention](../../guide/users/recommendations/public-apis.md#wildcard-imports).
diff --git a/docs/extensions/official/runtime-objects.md b/docs/extensions/official/runtime-objects.md
@@ -20,4 +20,4 @@ defaultdict(<class 'dict'>, {'runtime-objects': {'object': <function parse at 0x
 defaultdict(<class 'dict'>, {'runtime-objects': {'object': <class '_griffe.models.Module'>}})
 ```
 
-It can be useful in combination with mkdocstrings-python and custom templates, to iterate on object values or their attributes who couldn't be loaded by Griffe itself (for example objects built dynamically and loaded as attributes won't have "members" to iterate on).
+It can be useful in combination with mkdocstrings-python and custom templates, to iterate over object values or their attributes that couldn't be loaded by Griffe itself (for example, objects built dynamically and loaded as attributes won't have "members" to iterate over).
diff --git a/docs/extensions/official/sphinx.md b/docs/extensions/official/sphinx.md
@@ -9,7 +9,7 @@
 
 ---
 
-This extension reads Sphinx-comments above attribute assignments to use them as docstrings.
+This extension reads Sphinx comments placed above attribute assignments and uses them as docstrings.
 
 ```python
 #: Summary of `module_attr`. 
@@ -29,7 +29,7 @@ class Hello:
         self.instance_attr = "hello"
 ```
 
-Comments are treated exactly like regular docstrings: they are "cleaned" (dedented, stripped of leading and trailing new lines) and contain any markup you want, be it Markdown, rST, AsciiDoc, etc.
+Comments are treated exactly like regular docstrings: they are "cleaned" (dedented and stripped of leading and trailing newlines) and can contain any markup you want, be it Markdown, rST, AsciiDoc, etc.
 
 Trailing comments are not supported:
 
diff --git a/docs/extensions/official/typingdoc.md b/docs/extensions/official/typingdoc.md
@@ -7,7 +7,7 @@
 
 ---
 
-This extension reads docstrings for parameters, return values and more from type annotation using [`Annotated`][typing.Annotated] and the [`Doc`][typing_extensions.Doc] class suggested in [PEP 727](https://peps.python.org/pep-0727/). Documenting parameters and return values this way makes it possible to completely avoid relying on a particular "docstring style" (Google, Numpydoc, Sphinx, etc.) and just use plain markup in module/classes/function docstrings. Docstrings therefore do not have to be parsed at all.
+This extension reads docstrings for parameters, return values and more from type annotations using [`Annotated`][typing.Annotated] and the [`Doc`][typing_extensions.Doc] class suggested in [PEP 727](https://peps.python.org/pep-0727/). Documenting parameters and return values this way makes it possible to completely avoid relying on a particular "docstring style" (Google, Numpydoc, Sphinx, etc.) and just use plain markup in module/classes/function docstrings. Docstrings therefore do not have to be parsed at all.
 
 ```python
 from typing import Annotated as An
diff --git a/docs/getting-help.md b/docs/getting-help.md
@@ -4,4 +4,4 @@ If you have a quick question regarding Griffe, ask on our [Gitter channel](https
 
 For more complex questions, or actual issues that require showing code and configuration, please create [new Q/A discussions](https://github.com/mkdocstrings/griffe/discussions/categories/q-a) or [new bug reports](https://github.com/mkdocstrings/griffe/issues) respectively. Make sure to search previous discussions and issues to avoid creating duplicates. Also make sure to read our documentation before asking questions or opening bug reports. Don't hesitate to report unclear or missing documentation, we will do our best to improve it.
 
-In any case (quick or complex questions) please remember to be **kind**, and to follow our [code of conduct](code-of-conduct.md). The people helping you do so voluntarily, on their free time. Be respectful of their time, and of your own. Help them help you by providing all the necessary information in minimal, reproducible examples. When creating a bug report, make sure to fill out the issue template.
+In any case (quick or complex questions) please remember to be **kind**, and to follow our [code of conduct](code-of-conduct.md). The people helping you do so voluntarily, in their free time. Be respectful of their time, and of your own. Help them help you by providing all the necessary information in minimal, reproducible examples. When creating a bug report, make sure to fill out the issue template.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,8 +1,8 @@
 # Getting started
 
-To get started with Griffe, see [how to install it](installation.md) and [how to use it](introduction.md) with a short introduction. We also provide a [playground](playground.md) if you want to try it directly in your browser without actually installing it.
+To begin using Griffe, refer to [Installation](installation.md) and take a look at our [short introduction](introduction.md). If you'd like to experiment with Griffe without installing it, try our [playground](playground.md) directly in your browser.
 
-If you need help, if you have questions, or if you would like to contribute to the project, feel free to reach out to the community! You can open [new discussions on GitHub](https://github.com/mkdocstrings/griffe/discussions), or join our [Gitter channel](https://app.gitter.im/#/room/#mkdocstrings_griffe:gitter.im){ target="_blank" } for a quick chat.
+If you have questions, need help, or want to contribute, feel free to reach out to the community! You can open [new discussions on GitHub](https://github.com/mkdocstrings/griffe/discussions) or join our [Gitter channel](https://app.gitter.im/#/room/#mkdocstrings_griffe:gitter.im){ target="_blank" } for a quick chat.
 
 - [Installation](installation.md)
 - [Introduction (short tour)](introduction.md)
diff --git a/docs/guide.md b/docs/guide.md
@@ -1,23 +1,22 @@
 # Guide
 
-Welcome to the Griffe guide! This guide is composed of a series of topics on how to use Griffe, as well as an explanation of the project's inner workings. Although the project's explanation is more targeted at contributors, users are welcome to read it too, as it helps understanding further how Griffe works and how to best use it.
-
+Welcome to the Griffe guide! Here, you’ll find a series of topics on using Griffe, along with an explanation of the project’s inner workings. Although the more detailed explanations are primarily intended for contributors, users are encouraged to read them as well, since this can deepen their understanding of Griffe and help them make the most of it.
 
 <div class="grid cards" markdown>
 
 -   :fontawesome-solid-user:{ .lg .middle } **User guide**
 
     ---
 
-    A series of topics for Griffe users.
+    A collection of topics for Griffe users.
 
     [:octicons-arrow-right-24: Browse the user guide](guide/users.md)
 
 -   :fontawesome-solid-helmet-safety:{ .lg .middle } **Contributor guide**
 
     ---
 
-    Explanation of the project, and more, for Griffe contributors.
+    Explanation of the project and more, for Griffe contributors.
 
     [:octicons-arrow-right-24: Browse the contributor guide](guide/contributors.md)
 
diff --git a/docs/guide/users/checking.md b/docs/guide/users/checking.md
@@ -31,7 +31,7 @@ $ griffe check mypackage -b 8afcfd6e
 
 TIP: **Important:** Remember that the base is the most recent reference, and the one we compare it against is the oldest one.
 
-The package name you pass to `griffe check` must be found relatively to the repository root. For Griffe to find packages in subfolders, pass the parent subfolder to the `--search` or `-s` option. Example for `src`-layouts:
+The package name you pass to `griffe check` must be found relative to the repository root. For Griffe to find packages in subfolders, pass the parent subfolder to the `--search` or `-s` option. Example for `src`-layouts:
 
 ```console
 $ griffe check -s src griffe
@@ -158,7 +158,7 @@ def greet(name, prefix):
 greet("hello", "world")
 ```
 
-NOTE: Moving required parameters around is not really an API breakage, depending on our definition of API, since this won't raise immediate errors like `TypeError`. The function expects a number of arguments, and the developer pass it this same number of arguments: the contract is fulfilled. But parameters very often have specific meaning, and changing their order will *silently lead* (no immediate error) to incorrect behavior, potentially making it difficult to detect, understand and fix the issue. That is why it is important to warn developers about such changes.
+NOTE: Moving required parameters around is not really an API breakage, depending on our definition of API, since this won't raise immediate errors like `TypeError`. The function expects a number of arguments, and the developer passes it this same number of arguments: the contract is fulfilled. But parameters very often have specific meaning, and changing their order will *silently lead* (no immediate error) to incorrect behavior, potentially making it difficult to detect, understand and fix the issue. That is why it is important to warn developers about such changes.
 
 > TIP: **Hint**  
 > If you often add, move or remove parameters, consider making them keyword-only, so that their order doesn't matter.
diff --git a/docs/guide/users/extending.md b/docs/guide/users/extending.md
@@ -128,7 +128,7 @@ For a more concrete example, let say that we visit (or inspect) an AST (or objec
 - it will instantiate a [Function][griffe.Function]
 - then it will go back up and finish walking since there are no more nodes to walk through
 
-Every time the agent enters a node, creates an object instance, or finish handling members of an object, it will trigger an event.
+Every time the agent enters a node, creates an object instance, or finishes handling members of an object, it will trigger an event.
 
 The flow of events is drawn in the following flowchart:
 
@@ -182,7 +182,7 @@ class event_mod_members event
 classDef event stroke:#3cc,stroke-width:2
 ```
 
-Hopefully this flowchart gave you a pretty good idea of what happens when Griffe collects data from a Python module. The next section will explain in more details the different events that are triggered, and how to hook onto them in your extensions.
+Hopefully this flowchart gives you a pretty good idea of what happens when Griffe collects data from a Python module. The next section will explain in more details the different events that are triggered, and how to hook onto them in your extensions.
 
 ### Events and hooks
 
@@ -201,7 +201,7 @@ There are 3 generic **analysis events**:
 
 - [`on_node`][griffe.Extension.on_node]: The "on node" events are triggered when the agent (visitor or inspector) starts handling a node in the tree (AST or object tree).
 - [`on_instance`][griffe.Extension.on_instance]: The "on instance" events are triggered when the agent just created an instance of [Module][griffe.Module], [Class][griffe.Class], [Function][griffe.Function], or [Attribute][griffe.Attribute], and added it as a member of its parent. The "on instance" event is **not** triggered when an [Alias][griffe.Alias] is created.
-- [`on_members`][griffe.Extension.on_members]: The "on members" events are triggered when the agent just finished handling all the members of an object. Functions and attributes do not have members, so there are no "on members" event for these two kinds.
+- [`on_members`][griffe.Extension.on_members]: The "on members" events are triggered when the agent just finished handling all the members of an object. Functions and attributes do not have members, so there are no "on members" events for these two kinds.
 
 There are also specific **analysis events** for each object kind:
 
@@ -456,7 +456,7 @@ class MyExtension(griffe.Extension):
 
 ### Full example
 
-The following example shows how one could write a "dynamic docstrings" extension that dynamically import objects that declare their docstrings dynamically, to improve support for such docstrings. The extension is configurable to run only on user-selected objects.
+The following example shows how one could write a "dynamic docstrings" extension that dynamically imports objects that declare their docstrings dynamically, to improve support for such docstrings. The extension is configurable to run only on user-selected objects.
 
 Package structure (or just write your extension in a local script):
 
diff --git a/docs/guide/users/loading.md b/docs/guide/users/loading.md
@@ -187,7 +187,7 @@ The [Navigating](navigating.md) topic will tell you more about aliases and how t
 
 ### Modules collection
 
-In the first section of this page, we briefly mentioned that Griffe always loads the entire package containing the object you requested. One of the reason it always load entire packages and not just single, isolated objects, is that alias resolution requires all objects of a package to be loaded. Which means that if an alias points to an object that is part of *another* package, it can only be resolved if the *other* package is *also loaded*. For example:
+In the first section of this page, we briefly mentioned that Griffe always loads the entire package containing the object you requested. One of the reasons it always loads entire packages and not just single, isolated objects, is that alias resolution requires all objects of a package to be loaded. Which means that if an alias points to an object that is part of *another* package, it can only be resolved if the *other* package is *also loaded*. For example:
 
 ```tree title="File layout"
 ./
diff --git a/docs/guide/users/navigating.md b/docs/guide/users/navigating.md
diff --git a/docs/guide/users/recommendations/docstrings.md b/docs/guide/users/recommendations/docstrings.md
diff --git a/docs/guide/users/recommendations/public-apis.md b/docs/guide/users/recommendations/public-apis.md
diff --git a/docs/guide/users/recommendations/python-code.md b/docs/guide/users/recommendations/python-code.md
diff --git a/docs/guide/users/serializing.md b/docs/guide/users/serializing.md

Original file line number	Diff line number	Diff line change
`@@ -9,4 +9,4 @@`
`9`	`9`
`10`	`10`	`---`
`11`	`11`
`12`		`-This extension marks every objects that was imported with a redundant alias as public. See our documentation on the [redundant aliases convention](../../guide/users/recommendations/public-apis.md#redundant-aliases).`
	`12`	`+This extension marks every object that was imported with a redundant alias as public. See our documentation on the [redundant aliases convention](../../guide/users/recommendations/public-apis.md#redundant-aliases).`
Original file line number	Diff line number	Diff line change
`@@ -4,4 +4,4 @@ If you have a quick question regarding Griffe, ask on our [Gitter channel](https`
`4`	`4`
`5`	`5`	For more complex questions, or actual issues that require showing code and configuration, please create [new Q/A discussions](https://github.com/mkdocstrings/griffe/discussions/categories/q-a) or [new bug reports](https://github.com/mkdocstrings/griffe/issues) respectively. Make sure to search previous discussions and issues to avoid creating duplicates. Also make sure to read our documentation before asking questions or opening bug reports. Don't hesitate to report unclear or missing documentation, we will do our best to improve it.
`6`	`6`
`7`		`-In any case (quick or complex questions) please remember to be kind, and to follow our [code of conduct](code-of-conduct.md). The people helping you do so voluntarily, on their free time. Be respectful of their time, and of your own. Help them help you by providing all the necessary information in minimal, reproducible examples. When creating a bug report, make sure to fill out the issue template.`
	`7`	`+In any case (quick or complex questions) please remember to be kind, and to follow our [code of conduct](code-of-conduct.md). The people helping you do so voluntarily, in their free time. Be respectful of their time, and of your own. Help them help you by providing all the necessary information in minimal, reproducible examples. When creating a bug report, make sure to fill out the issue template.`