10000 refactor: Remove deprecated parts · mkdocstrings/mkdocstrings@0a90a47 · GitHub
[go: up one dir, main page]
Skip to content

Commit 0a90a47

Browse files
pawamoypawamoy
committed
refactor: Remove deprecated parts
- Base collector class - Base renderer class - Watch feature - Selection and rendering keys support (YAML options) - `mkdocstrings.handlers` namespace (when importing handlers and finding templates)
1 parent 40c4693 commit 0a90a47

File tree

11 files changed

+107
-402
lines changed

11 files changed

+107
-402
lines changed

‎config/mypy.ini

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,3 @@ ignore_missing_imports = true
33
exclude = tests/fixtures/
44
warn_unused_ignores = true
55
show_error_codes = true
6-
namespace_packages = true
7-
explicit_package_bases = true

‎config/ruff.toml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,6 @@ ignore = [
6565
"E501", # Line too long
6666
"ERA001", # Commented out code
6767
"G004", # Logging statement uses f-string
68-
"INP001", # File is part of an implicit namespace package
6968
"PLR0911", # Too many return statements
7069
"PLR0912", # Too many branches
7170
"PLR0913", # Too many arguments to function call

‎docs/usage/handlers.md

Lines changed: 11 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,8 @@ Since version 0.18, a new, experimental Python handler is available.
1414
It is based on [Griffe](https://github.com/mkdocstrings/griffe),
1515
which is an improved version of [pytkdocs](https://github.com/mkdocstrings/pytkdocs).
1616

17-
Note that the experimental handler does not yet support third-party libraries
18-
like Django, Marshmallow, Pydantic, etc.
19-
It is also not completely ready to handle dynamically built objects,
20-
like classes built with a call to `type(...)`.
21-
For most other cases, the experimental handler will work just fine.
17+
Note that the experimental handler does not yet support all third-party libraries
18+
that the legacy handler supported.
2219

2320
If you want to keep using the legacy handler as long as possible,
2421
you can depend on `mkdocstrings-python-legacy` directly,
@@ -51,18 +48,13 @@ dependencies = [
5148
]
5249
```
5350

54-
#### Handler options
55-
56-
- `setup_commands` is not yet implemented. In most cases, you won't need it,
57-
since by default the new handler does not execute the code.
58-
5951
#### Selection options
6052

6153
WARNING: Since *mkdocstrings* 0.19, the YAML `selection` key is merged into the `options` key.
6254

6355
- [x] `filters` is implemented, and used as before.
6456
- [x] `members` is implemented, and used as before.
65-
- [ ] `inherited_members` is not yet implemented.
57+
- [x] `inherited_members` is implemented.
6658
- [x] `docstring_style` is implemented, and used as before,
6759
except for the `restructured-text` style which is renamed `sphinx`.
6860
Numpy-style is now built-in, so you can stop depending on `pytkdocs[numpy-style]`
@@ -83,13 +75,13 @@ WARNING: Since *mkdocstrings* 0.19, the YAML `rendering` key is merged into the
8375
Every previous option is supported.
8476
Additional options are available:
8577

86-
- `separate_signature`: Render the signature (or attribute value) in a code block below the heading,
78+
- [x] `separate_signature`: Render the signature (or attribute value) in a code block below the heading,
8779
instead as inline code. Useful for long signatures. If Black is installed,
8880
the signature is formatted. Default: `False`.
89-
- `line_length`: The maximum line length to use when formatting signatures. Default: `60`.
90-
- `show_submodules`: Whether to render submodules of a module when iterating on children.
81+
- [x] `line_length`: The maximum line length to use when formatting signatures. Default: `60`.
82+
- [x] `show_submodules`: Whether to render submodules of a module when iterating on children.
9183
Default: `False`.
92-
- `docstring_section_style`: The style to use to render docstring sections such as attributes,
84+
- [x] `docstring_section_style`: The style to use to render docstring sections such as attributes,
9385
parameters, etc. Available styles: `table` (default), `list` and `spacy`. The SpaCy style
9486
is a poor implementation of their [table style](https://spacy.io/api/doc/#init).
9587
We are open to improvements through PRs!
@@ -99,34 +91,8 @@ See [all the handler's options](https://mkdocstrings.github.io/python/usage/).
9991
#### Templates
10092

10193
Templates are mostly the same as before, but the file layout has changed,
102-
as well as some file names. Here is the new tree:
103-
104-
```
105-
📁 theme/
106-
├── 📄 attribute.html
107-
├── 📄 children.html
108-
├── 📄 class.html
109-
├── 📁 docstring/
110-
│   ├── 📄 admonition.html
111-
│   ├── 📄 attributes.html
112-
│   ├── 📄 examples.html
113-
│   ├── 📄 other_parameters.html
114-
│   ├── 📄 parameters.html
115-
│   ├── 📄 raises.html
116-
│   ├── 📄 receives.html
117-
│   ├── 📄 returns.html
118-
│   ├── 📄 warns.html
119-
│   └── 📄 yields.html
120-
├── 📄 docstring.html
121-
├── 📄 expression.html
122-
├── 📄 function.html
123-
├── 📄 labels.html
124-
├── 📄 module.html
125-
└── 📄 signature.html
126-
```
127-
128-
See them [in the handler repository](https://github.com/mkdocstrings/python/tree/8fc8ea5b112627958968823ef500cfa46b63613e/src/mkdocstrings_handlers/python/templates/material). See the documentation about the Python handler templates:
129-
https://mkdocstrings.github.io/python/customization/#templates.
94+
as well as some file names.
95+
See [the documentation about the Python handler templates](https://mkdocstrings.github.io/python/usage/customization/#templates).
13096

13197
## Custom handlers
13298

@@ -213,7 +179,7 @@ If your theme's HTML requires CSS to go along with it, put it into a file named
213179
`mkdocstrings_handlers/custom_handler/templates/some_theme/style.css`, then this will be
214180
included into the final site automatically if this handler is ever used.
215181
Alternatively, you can put the CSS as a string into the `extra_css` variable of
216-
your renderer.
182+
your handler.
217183

218184
Finally, it's possible to entirely omit templates, and tell *mkdocstrings*
219185
to use the templates of another handler. In you handler, override the
@@ -225,7 +191,7 @@ from mkdocstrings.handlers.base import BaseHandler
225191

226192

227193
class CobraHandler(BaseHandler):
228-
def get_templates_dir(self, handler: str) -> Path:
194+
def get_templates_dir(self, handler: str | None = None) -> Path:
229195
# use the python handler templates
230196
# (it assumes the python handler is installed)
231197
return super().get_templates_dir("python")

‎docs/usage/index.md

Lines changed: 0 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -116,9 +116,6 @@ The above is equivalent to:
116116
- `enabled` **(New in version 0.20)**: Whether to enable the plugin. Defaults to `true`.
117117
Can be used to reduce build times when doing local development.
118118
Especially useful when used with environment variables (see example below).
119-
- `watch` **(deprecated)**: A list of directories to watch while serving the documentation.
120-
See [Watch directories](#watch-directories). Deprecated in favor of the now built-in
121-
[`watch` feature of MkDocs](https://www.mkdocs.org/user-guide/configuration/#watch).
122119

123120
!!! example
124121
```yaml title="mkdocs.yml"
@@ -334,30 +331,3 @@ plugins:
334331
- mkdocstrings:
335332
enable_inventory: false
336333
```
337-
338-
## Watch directories
339-
340-
DANGER: **Deprecated since version 0.19.**
341-
Instead, use the built-in [`watch` feature of MkDocs](https://www.mkdocs.org/user-guide/configuration/#watch).
342-
343-
You can add directories to watch with the `watch` key.
344-
It accepts a list of paths.
345-
346-
```yaml title="mkdocs.yml"
347-
plugins:
348-
- mkdocstrings:
349-
watch:
350-
- src/my_package_1
351-
- src/my_package_2
352-
```
353-
354-
When serving your documentation
355-
and a change occur in one of the listed path,
356-
MkDocs will rebuild the site and reload the current page.
357-
358-
NOTE: **The `watch` feature doesn't have special effects.**
359-
Adding directories to the `watch` list doesn't have any other effect than watching for changes.
360-
For example, it will not tell the Python handler to look for packages in these paths
361-
(the paths are not added to the `PYTHONPATH` variable).
362-
If you want to tell Python where to look for packages and modules,
363-
see [Python Handler: Finding modules](https://mkdocstrings.github.io/python/usage/#finding-modules).

‎pyproject.toml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,6 @@ plugins = [
6565

6666
[tool.pdm.build]
6767
package-dir = "src"
68-
includes = ["src/mkdocstrings"]
6968
editable-backend = "editables"
7069

7170
[tool.pdm.dev-dependencies]

‎src/mkdocstrings/__init__.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
"""mkdocstrings package.
2+
3+
Automatic documentation from sources, for MkDocs.
4+
"""

‎src/mkdocstrings/extension.py

Lines changed: 6 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -12,19 +12,17 @@
1212
```yaml
1313
::: some.identifier
1414
handler: python
15-
selection:
15+
options:
1616
option1: value1
1717
option2:
18-
- value2a
19-
- value2b
20-
rendering:
18+
- value2a
19+
- value2b
2120
option_x: etc
2221
```
2322
"""
2423

2524
from __future__ import annotations
2625

27-
import functools
2826
import re
2927
from collections import ChainMap
3028
from typing import TYPE_CHECKING, Any, MutableSequence
@@ -184,13 +182,7 @@ def _process_block(
184182

185183
global_options = handler_config.get("options", {})
186184
local_options = config.get("options", {})
187-
deprecated_global_options = ChainMap(handler_config.get("selection", {}), handler_config.get("rendering", {}))
188-
deprecated_local_options = ChainMap(config.get("selection", {}), config.get("rendering", {}))
189-
190-
options = ChainMap(local_options, deprecated_local_options, global_options, deprecated_global_options)
191-
192-
if deprecated_global_options or deprecated_local_options:
193-
self._warn_about_options_key()
185+
options = ChainMap(local_options, global_options)
194186

195187
if heading_level:
196188
options = ChainMap(options, {"heading_level": heading_level}) # like setdefault
@@ -200,12 +192,12 @@ def _process_block(
200192
data: CollectorItem = handler.collect(identifier, options)
201193
except CollectionError as exception:
202194
log.error(str(exception)) # noqa: TRY400
203-
if PluginError is SystemExit: # When MkDocs 1.2 is sufficiently common, this can be dropped.
195+
if PluginError is SystemExit: # TODO: when MkDocs 1.2 is sufficiently common, this can be dropped.
204196
log.error(f"Error reading page '{self._autorefs.current_page}':") # noqa: TRY400
205197
raise PluginError(f"Could not collect '{identifier}'") from exception
206198

207199
if handler_name not in self._updated_envs: # We haven't seen this handler before on this document.
208-
log.debug("Updating renderer's env")
200+
log.debug("Updating handler's rendering env")
209201
handler._update_env(self.md, self._config)
210202
self._updated_envs.add(handler_name)
211203

@@ -221,11 +213,6 @@ def _process_block(
221213

222214
return rendered, handler, data
223215

224-
@classmethod
225-
@functools.lru_cache(maxsize=None) # Warn only once
226-
def _warn_about_options_key(cls) -> None:
227-
log.info("DEPRECATION: 'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key")
228-
229216

230217
class _PostProcessor(Treeprocessor):
231218
def run(self, root: Element) -> None:

‎src/mkdocstrings/handlers/__init__.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
"""Handlers module."""

0 commit comments

Comments
 (0)
0