diff --git a/.copier-answers.yml b/.copier-answers.yml index 9869a311..9c4832f4 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier -_commit: 0.16.5 +_commit: 0.16.9 _src_path: gh:pawamoy/copier-pdm author_email: pawamoy@pm.me author_fullname: Timothée Mazzucotelli diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ee707a1..16d83845 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,19 @@ 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). +## [1.6.3](https://github.com/mkdocstrings/python/releases/tag/1.6.3) - 2023-09-11 + +[Compare with 1.6.2](https://github.com/mkdocstrings/python/compare/1.6.2...1.6.3) + +### Bug Fixes + +- Make `load_external_modules` a global-only option ([266f41f](https://github.com/mkdocstrings/python/commit/266f41f2033e034060001bc2bed376b4f3a8d7b8) by Timothée Mazzucotelli). [Issue #87](https://github.com/mkdocstrings/python/issues/87) +- Never fail when trying to format code with Black ([df24bbc](https://github.com/mkdocstrings/python/commit/df24bbc640886e1da2d00a3b58c1aa7736cb1eeb) by Timothée Mazzucotelli). + +### Code Refactoring + +- Wrap docstring section elements (list style) in code tags to prevent spell checker errors ([1ae8dd8](https://github.com/mkdocstrings/python/commit/1ae8dd89cddd67c09d7d30c59b9013516cea2924) by Timothée Mazzucotelli). + ## [1.6.2](https://github.com/mkdocstrings/python/releases/tag/1.6.2) - 2023-09-05 [Compare with 1.6.1](https://github.com/mkdocstrings/python/compare/1.6.1...1.6.2) diff --git a/docs/css/mkdocstrings.css b/docs/css/mkdocstrings.css index fe191c8c..727a614c 100644 --- a/docs/css/mkdocstrings.css +++ b/docs/css/mkdocstrings.css @@ -9,6 +9,7 @@ a.external::after, a.autorefs-external::after { /* https://primer.style/octicons/arrow-up-right-24 */ mask-image: url('data:image/svg+xml,'); + -webkit-mask-image: url('data:image/svg+xml,'); content: ' '; display: inline-block; diff --git a/docs/usage/configuration/docstrings.md b/docs/usage/configuration/docstrings.md index 87944a09..fcb9a19a 100644 --- a/docs/usage/configuration/docstrings.md +++ b/docs/usage/configuration/docstrings.md @@ -88,21 +88,11 @@ def greet(name: str) -> str: The options for the docstring parser. -Both Google and Numpy styles offer the following options: - -- `ignore_init_summary` ([`bool`][], default `False`): whether to discard - the one-line summary of `__init__` methods. - It is useful when combined with the [`merge_init_into_class`][] option. -- `trim_doctest_flags` ([`bool`][], default `True`): remove the - [doctest flags](https://docs.python.org/3/library/doctest.html#option-flags){ .external } - written as comments in `pycon` snippets within a docstring. These flags are used - to alter the behavior of [`doctest`][] when testing docstrings, - and should not be visible in your docs. +- [Google-style options](https://mkdocstrings.github.io/griffe/docstrings/#parser-options){ .external } +- [Numpydoc-style options](https://mkdocstrings.github.io/griffe/docstrings/#parser-options_1){ .external } The Sphinx style does not offer any option. -See the API documentation of the available parsers in [`griffe.docstrings`][]. - ```yaml title="in mkdocs.yml (global configuration)" plugins: - mkdocstrings: @@ -112,7 +102,6 @@ plugins: docstring_options: ignore_init_summary: false trim_doctest_flags: true - ``` ```md title="or in docs/some_page.md (local configuration)" diff --git a/duties.py b/duties.py index 1e37569f..8e3dbf64 100644 --- a/duties.py +++ b/duties.py @@ -4,21 +4,17 @@ import os import sys +from importlib.metadata import version as pkgversion from pathlib import Path from typing import TYPE_CHECKING, Any from duty import duty from duty.callables import black, blacken_docs, coverage, lazy, mkdocs, mypy, pytest, ruff, safety -if sys.version_info < (3, 8): - from importlib_metadata import version as pkgversion -else: - from importlib.metadata import version as pkgversion - - if TYPE_CHECKING: from duty.context import Context + PY_SRC_PATHS = (Path(_) for _ in ("src", "tests", "duties.py", "scripts")) PY_SRC_LIST = tuple(str(_) for _ in PY_SRC_PATHS) PY_SRC = " ".join(PY_SRC_LIST) diff --git a/mkdocs.yml b/mkdocs.yml index 4bf8abe1..31544367 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -148,6 +148,7 @@ plugins: docstring_options: ignore_init_summary: true docstring_section_style: list + filters: ["!^_"] heading_level: 1 inherited_members: true merge_init_into_class: true @@ -159,6 +160,7 @@ plugins: show_symbol_type_heading: true show_symbol_type_toc: true signature_crossrefs: true + summary: true - git-committers: enabled: !ENV [DEPLOY, false] repository: mkdocstrings/python diff --git a/scripts/insiders.py b/scripts/insiders.py index 6f8d0d84..28ca1c87 100644 --- a/scripts/insiders.py +++ b/scripts/insiders.py @@ -39,11 +39,13 @@ class Feature: """Class representing an Insiders feature.""" name: str - ref: str + ref: str | None since: date | None project: Project | None - def url(self, rel_base: str = "..") -> str: # noqa: D102 + def url(self, rel_base: str = "..") -> str | None: # noqa: D102 + if not self.ref: + return None if self.project: rel_base = self.project.url return posixpath.join(rel_base, self.ref.lstrip("/")) @@ -56,7 +58,8 @@ def render(self, rel_base: str = "..", *, badge: bool = False) -> None: # noqa: ft_date = self.since.strftime("%B %d, %Y") # type: ignore[union-attr] new = f' :material-alert-decagram:{{ .new-feature .vibrate title="Added on {ft_date}" }}' project = f"[{self.project.name}]({self.project.url}) — " if self.project else "" - print(f"- [{'x' if self.since else ' '}] {project}[{self.name}]({self.url(rel_base)}){new}") + feature = f"[{self.name}]({self.url(rel_base)})" if self.ref else self.name + print(f"- [{'x' if self.since else ' '}] {project}{feature}{new}") @dataclass @@ -99,7 +102,7 @@ def load_goals(data: str, funding: int = 0, project: Project | None = None) -> d features=[ Feature( name=feature_data["name"], - ref=feature_data["ref"], + ref=feature_data.get("ref"), since=feature_data.get("since") and datetime.strptime(feature_data["since"], "%Y/%m/%d").date(), # noqa: DTZ007 project=project, diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 20515fdb..637636b9 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -108,7 +108,6 @@ class PythonHandler(BaseHandler): "filters": ["!^_[^_]"], "annotations_path": "brief", "preload_modules": None, - "load_external_modules": False, "allow_inspection": True, } """ @@ -189,6 +188,7 @@ def __init__( config_file_path: str | None = None, paths: list[str] | None = None, locale: str = "en", + load_external_modules: bool = False, **kwargs: Any, ) -> None: """Initialize the handler. @@ -198,10 +198,12 @@ def __init__( config_file_path: The MkDocs configuration file path. paths: A list of paths to use as Griffe search paths. locale: The locale to use when rendering content. + load_external_modules: Load external modules when resolving aliases. **kwargs: Same thing, but with keyword arguments. """ super().__init__(*args, **kwargs) self._config_file_path = config_file_path + self._load_external_modules = load_external_modules paths = paths or [] glob_base_dir = os.path.dirname(os.path.abspath(config_file_path)) if config_file_path else "." with chdir(glob_base_dir): @@ -282,7 +284,7 @@ def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem: raise CollectionError(str(error)) from error unresolved, iterations = loader.resolve_aliases( implicit=False, - external=final_config["load_external_modules"], + external=self._load_external_modules, ) if unresolved: logger.debug(f"{len(unresolved)} aliases were still unresolved after {iterations} iterations") @@ -372,11 +374,13 @@ def get_anchors(self, data: CollectorItem) -> tuple[str, ...]: # noqa: D102 (ig def get_handler( + *, theme: str, custom_templates: str | None = None, config_file_path: str | None = None, paths: list[str] | None = None, locale: str = "en", + load_external_modules: bool = False, **config: Any, # noqa: ARG001 ) -> PythonHandler: """Simply return an instance of `PythonHandler`. @@ -387,6 +391,7 @@ def get_handler( config_file_path: The MkDocs configuration file path. paths: A list of paths to use as Griffe search paths. locale: The locale to use when rendering content. + load_external_modules: Load external modules when resolving aliases. **config: Configuration passed to the handler. Returns: @@ -399,4 +404,5 @@ def get_handler( config_file_path=config_file_path, paths=paths, locale=locale, + load_external_modules=load_external_modules, ) diff --git a/src/mkdocstrings_handlers/python/rendering.py b/src/mkdocstrings_handlers/python/rendering.py index 46b34c01..ef4b5071 100644 --- a/src/mkdocstrings_handlers/python/rendering.py +++ b/src/mkdocstrings_handlers/python/rendering.py @@ -351,14 +351,17 @@ def do_filter_objects( @lru_cache(maxsize=1) def _get_black_formatter() -> Callable[[str, int], str]: try: - from black import Mode, format_str + from black import InvalidInput, Mode, format_str except ModuleNotFoundError: logger.info("Formatting signatures requires Black to be installed.") return lambda text, _: text def formatter(code: str, line_length: int) -> str: mode = Mode(line_length=line_length) - return format_str(code, mode=mode) + try: + return format_str(code, mode=mode) + except InvalidInput: + return code return formatter diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html index 296f1557..6dc82d66 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html @@ -40,7 +40,7 @@