Merge branch 'master' of github.com:mkdocstrings/python

pawamoy · pawamoy · commit f2eee9a33d98 · 2023-03-03T14:21:51.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,14 @@ 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 -->
+## [0.8.3](https://github.com/mkdocstrings/python/releases/tag/0.8.3) - 2023-01-04
+
+<small>[Compare with 0.8.2](https://github.com/mkdocstrings/python/compare/0.8.2...0.8.3)</small>
+
+### Code Refactoring
+- Change "unresolved aliases" log level to DEBUG ([dccb818](https://github.com/mkdocstrings/python/commit/dccb818f51278cc8799e2187a615d999a3ab86fb) by Timothée Mazzucotelli).
+
+
 ## [0.8.2](https://github.com/mkdocstrings/python/releases/tag/0.8.2) - 2022-11-19
 
 <small>[Compare with 0.8.1](https://github.com/mkdocstrings/python/compare/0.8.1...0.8.2)</small>
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -3,7 +3,7 @@
 ## Our Pledge
 
 In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
+contributors and maintainers pledge to make participation in our project and
 our community a harassment-free experience for everyone, regardless of age, body
 size, disability, ethnicity, gender identity and expression, level of experience,
 nationality, personal appearance, race, religion, or sexual identity and
@@ -39,7 +39,7 @@ response to any instances of unacceptable behavior.
 
 Project maintainers have the right and responsibility to remove, edit, or
 reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
+that are not aligned with this Code of Conduct, or to ban temporarily or
 permanently any contributor for other behaviors that they deem inappropriate,
 threatening, offensive, or harmful.
 
@@ -58,7 +58,7 @@ Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported by contacting the project team at pawamoy@pm.me. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
+obligated to maintain confidentiality concerning the reporter of an incident.
 Further details of specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -93,7 +93,7 @@ Scope and body are optional. Type can be:
 - `feat`: New feature.
 - `fix`: Bug fix.
 - `perf`: About performance.
-- `refactor`: Changes which are not features nor bug fixes.
+- `refactor`: Changes that are not features or bug fixes.
 - `style`: A change in code style/format.
 - `tests`: About tests.
 
@@ -111,7 +111,7 @@ Fixes #15.
 
 Link to any related issue in the Pull Request message.
 
-During review, we recommend using fixups:
+During the review, we recommend using fixups:
 
 ```bash
 # SHA is the SHA of the commit you want to fix
diff --git a/README.md b/README.md
@@ -37,7 +37,7 @@ dependencies = [
 ]
 ```
 
-You can also explicitely depend on the handler:
+You can also explicitly depend on the handler:
 
 ```toml title="pyproject.toml"
 # PEP 621 dependencies declaration
@@ -59,11 +59,11 @@ dependencies = [
   [Griffe](https://github.com/mkdocstrings/griffe).
 
 - **Support for type annotations:** Griffe collects your type annotations and *mkdocstrings* uses them
-  to display parameters types or return types. It is even able to automatically add cross-references
-  to other objects from your API, from the standard library or from third-party libraries!
+  to display parameter types or return types. It is even able to automatically add cross-references
+  to other objects from your API, from the standard library or third-party libraries!
   See [how to load inventories](https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories) to enable it.
 
-- **Recursive documentation of Python objects:** just use the module dotted-path as identifier, and you get the full
+- **Recursive documentation of Python objects:** just use the module dotted-path as an identifier, and you get the full
   module docs. You don't need to inject documentation for each class, function, etc.
 
 - **Support for documented attributes:** attributes (variables) followed by a docstring (triple-quoted string) will
@@ -77,7 +77,7 @@ dependencies = [
   *We do not support nested admonitions in docstrings!*
 
 - **Every object has a TOC entry:** we render a heading for each object, meaning *MkDocs* picks them into the Table
-  of Contents, which is nicely display by the Material theme. Thanks to *mkdocstrings* cross-reference ability,
+  of Contents, which is nicely displayed by the Material theme. Thanks to *mkdocstrings* cross-reference ability,
   you can reference other objects within your docstrings, with the classic Markdown syntax:
   `[this object][package.module.object]` or directly with `[package.module.object][]`
 
diff --git a/docs/customization.md b/docs/customization.md
@@ -124,7 +124,7 @@ See them [in the repository](https://github.com/mkdocstrings/python/tree/master/
 See the general *mkdocstrings* documentation to learn how to override them: https://mkdocstrings.github.io/theming/#templates.
 
 In preparation for Jinja2 blocks, which will improve customization,
-each one of these templates extends in fact a base version in `theme/_base`. Example:
+each one of these templates extends a base version in `theme/_base`. Example:
 
 ```html+jinja title="theme/docstring/admonition.html"
 {% extends "_base/docstring/admonition.html" %}
@@ -139,7 +139,7 @@ each one of these templates extends in fact a base version in `theme/_base`. Exa
 ```
 
 It means you will be able to customize only *parts* of a template
-without having to fully copy-paste it in your project:
+without having to fully copy-paste it into your project:
 
 ```jinja title="templates/theme/docstring.html"
 {% extends "_base/docstring.html" %}
diff --git a/docs/schema.json b/docs/schema.json
@@ -26,6 +26,14 @@
                   "base_url": {
                     "title": "Base URL used to build references URLs.",
                     "type": "string"
+                  },
+                  "domains": {
+                    "title": "Domains to import from the inventory.",
+                    "description": "If not defined it will only import 'py' domain.",
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
                   }
                 }
               }
@@ -132,8 +140,68 @@
               "type": "boolean",
               "default": false
             },
+            "show_docstring_attributes": {
+              "title": "Whether to display the \"Attributes\" section in the object's docstring.",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "boolean",
+              "default": true
+            },
+            "show_docstring_description": {
+              "title": "Whether to display the textual block (including admonitions) in the object's docstring.",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "boolean",
+              "default": true
+            },
+            "show_docstring_examples": {
+              "title": "Whether to display the \"Examples\" section in the object's docstring.",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "boolean",
+              "default": true
+            },
+            "show_docstring_other_parameters": {
+              "title": "Whether to display the \"Other Parameters\" section in the object's docstring.",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "boolean",
+              "default": true
+            },
+            "show_docstring_parameters": {
+              "title": "Whether to display the \"Parameters\" section in the object's docstring.",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "boolean",
+              "default": true
+            },
+            "show_docstring_raises": {
+              "title": "Whether to display the \"Raises\" section in the object's docstring.",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "boolean",
+              "default": true
+            },
+            "show_docstring_receives": {
+              "title": "Whether to display the \"Receives\" section in the object's docstring.",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "boolean",
+              "default": true
+            },
+            "show_docstring_returns": {
+              "title": "Whether to display the \"Returns\" section in the object's docstring.",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "boolean",
+              "default": true
+            },
+            "show_docstring_warns": {
+              "title": "Whether to display the \"Warns\" section in the object's docstring.",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "boolean",
+              "default": true
+            },
+            "show_docstring_yields": {
+              "title": "Whether to display the \"Yields\" section in the object's docstring.",
+              "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
+              "type": "boolean",
+              "default": true
+            },
             "show_source": {
-              "title": "Show the source code of this object..",
+              "title": "Show the source code of this object.",
               "markdownDescription": "https://mkdocstrings.github.io/python/usage/#globallocal-options",
               "type": "boolean",
               "default": true
@@ -203,4 +271,4 @@
     }
   },
   "additionalProperties": false
-}
+}
diff --git a/docs/usage.md b/docs/usage.md
@@ -74,7 +74,7 @@ plugins:
       do_something: false
 ```
 
-These options affect how the documentation is collected from sources and renderered:
+These options affect how the documentation is collected from sources and rendered:
 headings, members, docstrings, etc.
 
 ::: mkdocstrings_handlers.python.handler.PythonHandler.default_config
@@ -202,7 +202,7 @@ TIP: **This is the recommended method.**
     ```
 
 Except for case 1, which is supported by default, **we strongly recommend
-to set the path to your packages using this option, even if it works without it**
+setting the path to your packages using this option, even if it works without it**
 (for example because your project manager automatically adds `src` to PYTHONPATH),
 to make sure anyone can build your docs from any location on their filesystem.
 
@@ -211,7 +211,7 @@ to make sure anyone can build your docs from any location on their filesystem.
 WARNING: **This method has limitations.**  
 This method might work for you, with your current setup,
 but not for others trying your build your docs with their own setup/environment.
-We recommend to use the [`paths` method](#using-the-paths-option) instead.
+We recommend using the [`paths` method](#using-the-paths-option) instead.
 
 You can take advantage of the usual Python loading mechanisms.
 In Bash and other shells, you can run your command like this
@@ -270,7 +270,7 @@ In Bash and other shells, you can run your command like this
 WARNING: **This method has limitations.**  
 This method might work for you, with your current setup,
 but not for others trying your build your docs with their own setup/environment.
-We recommend to use the [`paths` method](#using-the-paths-option) instead.
+We recommend using the [`paths` method](#using-the-paths-option) instead.
 
 Install your package in the current environment, and run MkDocs:
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -29,7 +29,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "mkdocstrings>=0.19",
+    "mkdocstrings>=0.20",
     "griffe>=0.24",
 ]
 
@@ -98,7 +98,7 @@ tests = [
     "pytest-xdist>=2.4",
 ]
 typing = [
-    "mypy>=0.910",
+    "mypy>=0.911",
     "types-markdown>=3.3",
     "types-toml>=0.10",
 ]
diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py
@@ -2,14 +2,15 @@
 
 from __future__ import annotations
 
+import copy
 import glob
 import os
 import posixpath
 import re
 import sys
 from collections import ChainMap
 from contextlib import suppress
-from typing import Any, BinaryIO, Iterator, Optional, Tuple
+from typing import Any, BinaryIO, Iterator, Mapping, Optional, Tuple
 
 from griffe.agents.extensions import load_extensions
 from griffe.collections import LinesCollection, ModulesCollection
@@ -78,6 +79,16 @@ class PythonHandler(BaseHandler):
         "separate_signature": False,
         "line_length": 60,
         "merge_init_into_class": False,
+        "show_docstring_attributes": True,
+        "show_docstring_description": True,
+        "show_docstring_examples": True,
+        "show_docstring_other_parameters": True,
+        "show_docstring_parameters": True,
+        "show_docstring_raises": True,
+        "show_docstring_receives": True,
+        "show_docstring_returns": True,
+        "show_docstring_warns": True,
+        "show_docstring_yields": True,
         "show_source": True,
         "show_bases": True,
         "show_submodules": False,
@@ -118,6 +129,16 @@ class PythonHandler(BaseHandler):
         line_length (int): Maximum line length when formatting code/signatures. Default: `60`.
         merge_init_into_class (bool): Whether to merge the `__init__` method into the class' signature and docstring. Default: `False`.
         show_if_no_docstring (bool): Show the object heading even if it has no docstring or children with docstrings. Default: `False`.
+        show_docstring_attributes (bool): Whether to display the "Attributes" section in the object's docstring. Default: `True`.
+        show_docstring_description (bool): Whether to display the textual block (including admonitions) in the object's docstring. Default: `True`.
+        show_docstring_examples (bool): Whether to display the "Examples" section in the object's docstring. Default: `True`.
+        show_docstring_other_parameters (bool): Whether to display the "Other Parameters" section in the object's docstring. Default: `True`.
+        show_docstring_parameters (bool): Whether to display the "Parameters" section in the object's docstring. Default: `True`.
+        show_docstring_raises (bool): Whether to display the "Raises" section in the object's docstring. Default: `True`.
+        show_docstring_receives (bool): Whether to display the "Receives" section in the object's docstring. Default: `True`.
+        show_docstring_returns (bool): Whether to display the "Returns" section in the object's docstring. Default: `True`.
+        show_docstring_warns (bool): Whether to display the "Warns" section in the object's docstring. Default: `True`.
+        show_docstring_yields (bool): Whether to display the "Yields" section in the object's docstring. Default: `True`.
 
     Attributes: Signatures/annotations options:
         annotations_path (str): The verbosity for annotations path: `brief` (recommended), or `source` (as written in the source). Default: `"brief"`.
@@ -168,6 +189,7 @@ def load_inventory(
         in_file: BinaryIO,
         url: str,
         base_url: Optional[str] = None,
+        domains: list[str] | None = None,
         **kwargs: Any,
     ) -> Iterator[Tuple[str, str]]:
         """Yield items and their URLs from an inventory file streamed from `in_file`.
@@ -178,24 +200,28 @@ def load_inventory(
             in_file: The binary file-like object to read the inventory from.
             url: The URL that this file is being streamed from (used to guess `base_url`).
             base_url: The URL that this inventory's sub-paths are relative to.
+            domains: A list of domain strings to filter the inventory by, when not passed, "py" will be used.
             **kwargs: Ignore additional arguments passed from the config.
 
         Yields:
             Tuples of (item identifier, item URL).
         """
+        domains = domains or ["py"]
         if base_url is None:
             base_url = posixpath.dirname(url)
 
-        for item in Inventory.parse_sphinx(in_file, domain_filter=("py",)).values():  # noqa: WPS526
+        for item in Inventory.parse_sphinx(in_file, domain_filter=domains).values():  # noqa: WPS526
             yield item.name, posixpath.join(base_url, item.uri)
 
-    def collect(self, identifier: str, config: dict) -> CollectorItem:  # noqa: D102,WPS231
+    def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem:  # noqa: D102,WPS231
         module_name = identifier.split(".", 1)[0]
         unknown_module = module_name not in self._modules_collection
         if config.get("fallback", False) and unknown_module:
             raise CollectionError("Not loading additional modules during fallback")
 
-        final_config = ChainMap(config, self.default_config)
+        # See: https://github.com/python/typeshed/issues/8430
+        mutable_config = dict(copy.deepcopy(config))
+        final_config = ChainMap(mutable_config, self.default_config)
         parser_name = final_config["docstring_style"]
         parser_options = final_config["docstring_options"]
         parser = parser_name and Parser(parser_name)
@@ -216,7 +242,7 @@ def collect(self, identifier: str, config: dict) -> CollectorItem:  # noqa: D102
 
             unresolved, iterations = loader.resolve_aliases(implicit=False, external=False)
             if unresolved:
-                logger.warning(f"{len(unresolved)} aliases were still unresolved after {iterations} iterations")
+                logger.debug(f"{len(unresolved)} aliases were still unresolved after {iterations} iterations")
                 logger.debug(f"Unresolved aliases: {', '.join(sorted(unresolved))}")
 
         try:
@@ -232,8 +258,10 @@ def collect(self, identifier: str, config: dict) -> CollectorItem:  # noqa: D102
 
         return doc_object
 
-    def render(self, data: CollectorItem, config: dict) -> str:  # noqa: D102 (ignore missing docstring)
-        final_config = ChainMap(config, self.default_config)
+    def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:  # noqa: D102 (ignore missing docstring)
+        # See https://github.com/python/typeshed/issues/8430
+        mutabled_config = dict(copy.deepcopy(config))
+        final_config = ChainMap(mutabled_config, self.default_config)
 
         template = self.env.get_template(f"{data.kind.value}.html")
 
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring.html

Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@ classifiers = [`
`29`	`29`	`"Typing :: Typed",`
`30`	`30`	`]`
`31`	`31`	`dependencies = [`
`32`		`- "mkdocstrings>=0.19",`
	`32`	`+ "mkdocstrings>=0.20",`
`33`	`33`	`"griffe>=0.24",`
`34`	`34`	`]`
`35`	`35`
`@@ -98,7 +98,7 @@ tests = [`
`98`	`98`	`"pytest-xdist>=2.4",`
`99`	`99`	`]`
`100`	`100`	`typing = [`
`101`		`- "mypy>=0.910",`
	`101`	`+ "mypy>=0.911",`
`102`	`102`	`"types-markdown>=3.3",`
`103`	`103`	`"types-toml>=0.10",`
`104`	`104`	`]`