docs: Improve docs

Author: pawamoy

docs/customization.md

@@ -96,28 +96,28 @@ div.doc-contents:not(.first) {
 
 Templates are organized into the following tree:
 
-```
-📁 theme/
-├── 📄 attribute.html
-├── 📄 children.html
-├── 📄 class.html
-├── 📁 docstring/
-│   ├── 📄 admonition.html
-│   ├── 📄 attributes.html
-│   ├── 📄 examples.html
-│   ├── 📄 other_parameters.html
-│   ├── 📄 parameters.html
-│   ├── 📄 raises.html
-│   ├── 📄 receives.html
-│   ├── 📄 returns.html
-│   ├── 📄 warns.html
-│   └── 📄 yields.html
-├── 📄 docstring.html
-├── 📄 expression.html
-├── 📄 function.html
-├── 📄 labels.html
-├── 📄 module.html
-└── 📄 signature.html
+```tree result="text"
+theme/
+  attribute.html
+  children.html
+  class.html
+  docstring/
+  admonition.html
+  attributes.html
+  examples.html
+  other_parameters.html
+  parameters.html
+  raises.html
+  receives.html
+  returns.html
+  warns.html
+  yields.html
+  docstring.html
+  expression.html
+  function.html
+  labels.html
+  module.html
+  signature.html
 ```
 
 See them [in the repository](https://github.com/mkdocstrings/python/tree/master/src/mkdocstrings_handlers/python/templates/).

docs/usage.md

@@ -1,6 +1,6 @@
 # Usage
 
-WARNING: **This is the documentation for the NEW, EXPERIMENTAL Python handler.** 
+TIP: **This is the documentation for the NEW Python handler.** 
 To read the documentation for the LEGACY handler,
 go to the [legacy handler documentation](https://mkdocstrings.github.io/python-legacy).
 
@@ -17,7 +17,7 @@ Like every handler, the Python handler accepts both **global** and **local** opt
 
 Some options are **global only**, and go directly under the handler's name.
 
-- `import`: This option is used to import Sphinx-compatible objects inventories from other
+- `import`: this option is used to import Sphinx-compatible objects inventories from other
  documentation sites. For example, you can import the standard library
  objects inventory like this:
 
@@ -138,10 +138,10 @@ so that the current working directory has no impact on the build process:
 TIP: **This is the recommended method.**
 
 1. mkdocs.yml in root, package in root
- ```
- 📁 root/
- ├── 📄 mkdocs.yml
- └── 📁 package/
+ ```tree
+ root/
+   mkdocs.yml
+   package/
  ```
 
  ```yaml title="mkdocs.yml"
@@ -153,11 +153,11 @@ TIP: **This is the recommended method.**
  ```
 
 1. mkdocs.yml in root, package in subfolder
- ```
- 📁 root/
- ├── 📄 mkdocs.yml
- └── 📁 src/
- └── 📁 package/
+ ```tree
+ root/
+   mkdocs.yml
+   src/
+   package/
  ```
 
  ```yaml title="mkdocs.yml"
@@ -169,11 +169,11 @@ TIP: **This is the recommended method.**
  ```
 
 1. mkdocs.yml in subfolder, package in root
- ```
- 📁 root/
- ├── 📁 docs/
- │ └── 📄 mkdocs.yml
- └── 📁 package/
+ ```tree
+ root/
+   docs/
+   mkdocs.yml
+   package/
  ```
 
  ```yaml title="mkdocs.yml"
@@ -185,12 +185,12 @@ TIP: **This is the recommended method.**
  ```
 
 1. mkdocs.yml in subfolder, package in subfolder
- ```
- 📁 root/
- ├── 📁 docs/
- │ └── 📄 mkdocs.yml
- └── 📁 src/
- └── 📁 package/
+ ```tree
+ root/
+   docs/
+   mkdocs.yml
+   src/
+   package/
  ```
 
  ```yaml title="mkdocs.yml"
@@ -218,47 +218,47 @@ In Bash and other shells, you can run your command like this
 (note the prepended `PYTHONPATH=...`):
 
 1. mkdocs.yml in root, package in root
- ```
- 📁 root/
- ├── 📄 mkdocs.yml
- └── 📁 package/
+ ```tree
+ root/
+   mkdocs.yml
+   package/
  ```
 
  ```bash
  PYTHONPATH=. mkdocs build # actually not needed, default
  ```
 
 1. mkdocs.yml in root, package in subfolder
- ```
- 📁 root/
- ├── 📄 mkdocs.yml
- └── 📁 src/
- └── 📁 package/
+ ```tree
+ root/
+   mkdocs.yml
+   src/
+   package/
  ```
 
  ```bash
  PYTHONPATH=src mkdocs build
  ```
 
 1. mkdocs.yml in subfolder, package in root
- ```
- 📁 root/
- ├── 📁 docs/
- │ └── 📄 mkdocs.yml
- └── 📁 package/
+ ```tree
+ root/
+   docs/
+   mkdocs.yml
+   package/
  ```
 
  ```bash
  PYTHONPATH=. mkdocs build -f docs/mkdocs.yml
  ```
 
 1. mkdocs.yml in subfolder, package in subfolder
- ```
- 📁 root/
- ├── 📁 docs/
- │ └── 📄 mkdocs.yml
- └── 📁 src/
- └── 📁 package/
+ ```tree
+ root/
+   docs/
+   mkdocs.yml
+   src/
+   package/
  ```
 
  ```bash

scripts/gen_credits.py

@@ -1,5 +1,4 @@
 import re
-from importlib.metadata import metadata, PackageNotFoundError
 from itertools import chain
 from pathlib import Path
 from textwrap import dedent
@@ -8,6 +7,11 @@
 from jinja2 import StrictUndefined
 from jinja2.sandbox import SandboxedEnvironment
 
+try:
+ from importlib.metadata import metadata, PackageNotFoundError
+except ImportError:
+ from importlib_metadata import metadata, PackageNotFoundError
+
 project_dir = Path(".")
 pyproject = toml.load(project_dir / "pyproject.toml")
 project = pyproject["project"]

src/mkdocstrings_handlers/python/handler.py

@@ -88,7 +88,9 @@ class PythonHandler(BaseHandler):
  members_order (str): The members ordering to use. Options: `alphabetical` - order by the members names,
  `source` - order members as they appear in the source file. Default: `"alphabetical"`.
  filters (list[str] | None): A list of filters applied to filter objects based on their name.
- A filter starting with `!` will exclude matching objects instead of including them. Default: `["!^_[^_]"]`.
+ A filter starting with `!` will exclude matching objects instead of including them.
+ The `members` option takes precedence over `filters` (filters will still be applied recursively
+ to lower members in the hierarchy). Default: `["!^_[^_]"]`.
  group_by_category (bool): Group the object's children by categories: attributes, classes, functions, and modules. Default: `True`.
  show_submodules (bool): When rendering a module, show its submodules recursively. Default: `False`.