From 347ce76d074c0e3841df2d5162b54d3938d00453 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sat, 30 Apr 2022 12:40:13 +0200 Subject: [PATCH] refactor: Merge default configuration options in handler --- docs/usage.md | 2 +- src/mkdocstrings_handlers/python/handler.py | 56 +++++++++++---------- 2 files changed, 30 insertions(+), 28 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 51e6dd6b..0f735825 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -41,7 +41,7 @@ Option | Description ### Rendering -::: mkdocstrings_handlers.python.handler.PythonHandler.default_rendering_config +::: mkdocstrings_handlers.python.handler.PythonHandler.default_config rendering: show_root_toc_entry: false diff --git a/src/mkdocstrings_handlers/python/handler.py b/src/mkdocstrings_handlers/python/handler.py index 591a3129..1ca452e6 100644 --- a/src/mkdocstrings_handlers/python/handler.py +++ b/src/mkdocstrings_handlers/python/handler.py @@ -38,25 +38,17 @@ class PythonHandler(BaseHandler): of the `objects.inv` Sphinx inventory file. fallback_theme: The fallback theme. fallback_config: The configuration used to collect item during autorefs fallback. - default_collection_config: The default rendering options, - see [`default_collection_config`][mkdocstrings_handlers.python.handler.PythonHandler.default_collection_config]. - default_rendering_config: The default rendering options, - see [`default_rendering_config`][mkdocstrings_handlers.python.handler.PythonHandler.default_rendering_config]. + default_config: The default rendering options, + see [`default_config`][mkdocstrings_handlers.python.handler.PythonHandler.default_config]. """ domain: str = "py" # to match Sphinx's default domain enable_inventory: bool = True fallback_theme = "material" fallback_config: dict = {"fallback": True} - default_collection_config: dict = {"docstring_style": "google", "docstring_options": {}} - """The default collection options. - - Option | Type | Description | Default - ------ | ---- | ----------- | ------- - **`docstring_style`** | `"google" | "numpy" | "sphinx" | None` | The docstring style to use. | `"google"` - **`docstring_options`** | `dict[str, Any]` | The options for the docstring parser. | `{}` - """ - default_rendering_config: dict = { + default_config: dict = { + "docstring_style": "google", + "docstring_options": {}, "show_root_heading": False, "show_root_toc_entry": True, "show_root_full_path": True, @@ -81,30 +73,40 @@ class PythonHandler(BaseHandler): "annotations_path": "brief", } """ - Attributes: Default rendering options: + Attributes: Headings options: + heading_level (int): The initial heading level to use. Default: `2`. show_root_heading (bool): Show the heading of the object at the root of the documentation tree. Default: `False`. show_root_toc_entry (bool): If the root heading is not shown, at least add a ToC entry for it. Default: `True`. show_root_full_path (bool): Show the full Python path for the root object heading. Default: `True`. show_root_members_full_path (bool): Show the full Python path of every object. Default: `False`. show_object_full_path (bool): Show the full Python path of objects that are children of the root object (for example, classes in a module). When False, `show_object_full_path` overrides. Default: `False`. show_category_heading (bool): When grouped by categories, show a heading for each category. Default: `False`. + + Attributes: Members options: + members (list[str] | False | None): An explicit list of members to render. Default: `None`. + 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: `["!^_[^_]"]`. + group_by_category (bool): Group the object's children by categories: attributes, classes, functions, methods, and modules. Default: `True`. + show_submodules (bool): When rendering a module, show its submodules recursively. Default: `True`. + 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"`. + + Attributes: Docstrings options: + docstring_style (str): The docstring style to use: `google`, `numpy`, `sphinx`, or `None`. Default: `"google"`. + docstring_options (dict): The options for the docstring parser. See parsers under [`griffe.docstrings`][]. + docstring_section_style (str): The style used to render docstring sections. Options: `table`, `list`, `spacy`. Default: `"table"`. + line_length (int): Maximum line length when formatting code. 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`. + + Attributes: Signature/annotations options: annotations_path: The verbosity for annotations path: `brief` (recommended), or `source` (as written in the source). Default: `"brief"`. show_signature (bool): Show method and function signatures. Default: `True`. show_signature_annotations (bool): Show the type annotations in method and function signatures. Default: `False`. separate_signature (bool): Whether to put the whole signature in a code block below the heading. Default: `False`. - line_length (int): Maximum line length when formatting code. Default: `60`. - merge_init_into_class (bool): Whether to merge the `__init__` method into the class' signature and docstring. Default: `False`. - show_source (bool): Show the source code of this object. Default: `True`. + + Attributes: Additional options: show_bases (bool): Show the base classes of a class. Default: `True`. - show_submodules (bool): When rendering a module, show its submodules recursively. Default: `True`. - group_by_category (bool): Group the object's children by categories: attributes, classes, functions, methods, and modules. Default: `True`. - heading_level (int): The initial heading level to use. Default: `2`. - 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`. - docstring_section_style (str): The style used to render docstring sections. Options: `table`, `list`, `spacy`. Default: `table`. - members (list[str] | False | None): An explicit list of members to render. Default: `None`. - 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: `["!^_[^_]"]`. + show_source (bool): Show the source code of this object. Default: `True`. """ # noqa: E501 def __init__( @@ -167,7 +169,7 @@ def collect(self, identifier: str, config: dict) -> CollectorItem: # noqa: D102 if config.get("fallback", False) and unknown_module: raise CollectionError("Not loading additional modules during fallback") - final_config = ChainMap(config, self.default_collection_config) + final_config = ChainMap(config, self.default_config) parser_name = final_config["docstring_style"] parser_options = final_config["docstring_options"] parser = parser_name and Parser(parser_name) @@ -204,7 +206,7 @@ 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_rendering_config) + final_config = ChainMap(config, self.default_config) template = self.env.get_template(f"{data.kind.value}.html")