Skip to content

Commit

Permalink
refactor: Unify default configurations
Browse files Browse the repository at this point in the history
  • Loading branch information
@pawamoy
pawamoy committed May 28, 2022
1 parent c328088 commit 47c53fc
Showing 1 changed file with 46 additions and 46 deletions.
92 changes: 46 additions & 46 deletions src/mkdocstrings_handlers/python/handler.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,30 +61,8 @@ class PythonHandler(BaseHandler):
which we know will not generate any warnings.
"""

default_collection_config: dict = {"filters": ["!^_[^_]"]}
"""The default selection options.
Option | Type | Description | Default
------ | ---- | ----------- | -------
**`filters`** | `List[str]` | Filter members with regular expressions. | `[ "!^_[^_]" ]`
**`members`** | `Union[bool, List[str]]` | Explicitly select the object members. | *`pytkdocs` default: `True`*
If `members` is a list of names, filters are applied only on the members children (not the members themselves).
If `members` is `False`, none are selected.
If `members` is `True` or an empty list, filters are applied on all members and their children.
Members affect only the first layer of objects, while filters affect the whole object-tree recursively.
Every filters is run against every object name. An object can be un-selected by a filter and re-selected by the
next one:
- `"!^_"`: exclude all objects starting with an underscore
- `"^__"`: but select all objects starting with **two** underscores
Obviously one could use a single filter instead: `"!^_[^_]"`, which is the default.
"""

default_rendering_config: dict = {
default_config: dict = {
"filters": ["!^_[^_]"],
"show_root_heading": False,
"show_root_toc_entry": True,
"show_root_full_path": True,
Expand All @@ -100,24 +78,44 @@ class PythonHandler(BaseHandler):
"heading_level": 2,
"members_order": "alphabetical",
}
"""The default rendering options.
Option | Type | Description | Default
------ | ---- | ----------- | -------
**`show_root_heading`** | `bool` | Show the heading of the object at the root of the documentation tree. | `False`
**`show_root_toc_entry`** | `bool` | If the root heading is not shown, at least add a ToC entry for it. | `True`
**`show_root_full_path`** | `bool` | Show the full Python path for the root object heading. | `True`
**`show_object_full_path`** | `bool` | Show the full Python path of every object. | `False`
**`show_root_members_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. | `False`
**`show_category_heading`** | `bool` | When grouped by categories, show a heading for each category. | `False`
**`show_if_no_docstring`** | `bool` | Show the object heading even if it has no docstring or children with docstrings. | `False`
**`show_signature`** | `bool` | Show method and function signatures. | `True`
**`show_signature_annotations`** | `bool` | Show the type annotations in method and function signatures. | `False`
**`show_source`** | `bool` | Show the source code of this object. | `True`
**`show_bases`** | `bool` | Show the base classes of a class. | `True`
**`group_by_category`** | `bool` | Group the object's children by categories: attributes, classes, functions, methods, and modules. | `True`
**`heading_level`** | `int` | The initial heading level to use. | `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. | `alphabetical`
"""
**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
(i.e. the object referenced by the identifier after `:::`). 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 the root members. Default: `False`.
- `show_object_full_path` (`bool`): Show the full Python path of every object. Default: `False`.
- `show_category_heading` (`bool`): When grouped by categories, show a heading for each category. Default: `False`.
**Members options:**
- `members` (`list[str] | False | None`): An explicit list of members to render. Default: `None`.
- `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.
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`.
**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 [`pytkdocs.parsers.docstrings`][].
- `show_if_no_docstring` (`bool`): Show the object heading even if it has no docstring or children with docstrings. Default: `False`.
**Signatures/annotations options:**
- `show_signature` (`bool`): Show methods and functions signatures. Default: `True`.
- `show_signature_annotations` (`bool`): Show the type annotations in methods and functions signatures. Default: `False`.
**Additional options:**
- `show_bases` (`bool`): Show the base classes of a class. Default: `True`.
- `show_source` (`bool`): Show the source code of this object. Default: `True`.
""" # noqa: E501

def __init__( # noqa: WPS231
Expand All @@ -139,7 +137,7 @@ def __init__( # noqa: WPS231
*args: Handler name, theme and custom templates.
setup_commands: A list of python commands as strings to be executed in the subprocess before `pytkdocs`.
config_file_path: The MkDocs configuration file path.
paths: A list of paths to use as Griffe search paths.
paths: A list of paths to use as search paths.
**kwargs: Same thing, but with keyword arguments.
"""
logger.debug("Opening 'pytkdocs' subprocess")
Expand Down Expand Up @@ -251,10 +249,12 @@ def collect(self, identifier: str, config: dict) -> CollectorItem: # noqa: WPS2
Returns:
The collected object-tree.
"""
final_config = dict(self.default_collection_config)
final_config = {}
for option in ("filters", "members"):
if option in config:
final_config[option] = config[option]
elif option in self.default_config:
final_config[option] = self.default_config[option]

logger.debug("Preparing input")
json_input = json.dumps({"objects": [{"path": identifier, **final_config}]})
Expand Down Expand Up @@ -300,7 +300,7 @@ def teardown(self) -> None:
self.process.terminate()

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['category']}.html")

Expand Down Expand Up @@ -352,7 +352,7 @@ def get_handler(
custom_templates: Directory containing custom templates.
setup_commands: A list of commands as strings to be executed in the subprocess before `pytkdocs`.
config_file_path: The MkDocs configuration file path.
paths: A list of paths to use as Griffe search paths.
paths: A list of paths to use as search paths.
config: Configuration passed to the handler.
Returns:
Expand Down

0 comments on commit 47c53fc

Please sign in to comment.