doc: document the configuration dict and how to configure the app

Author: rafalkrupinski

README.md

@@ -33,3 +33,18 @@ Use the `-o`, `--output` option to write to a file instead of standard output:
 ```bash
 griffe2md markdown -o markdown.md
 ```
+
+`griffe2md` can be configured by either 'pyproject.toml' or 'griffe2md.toml' files. The latter can be placed either in '.config' or 'config' directory in the project root.
+
+'griffe2md.toml' file is structured as a simple key-value dictionary, e.g.:
+```toml
+docstring_style = "sphinx"
+```
+
+If you configure it in `pyproject.toml`, the configuration should go under 'tool.griffe2md' key:
+```toml
+[tool.griffe2md]
+docstring_style = "sphinx"
+```
+
+See [the documentation](https://mkdocstrings.github.io/griffe2md/reference/griffe2md/rendering/#griffe2md.rendering.ConfigDict) for reference.

src/griffe2md/config.py

@@ -4,8 +4,10 @@
 
 import logging
 import sys
+import typing
 from pathlib import Path
-from typing import Any
+
+from griffe2md import rendering
 
 # YORE: EOL 3.10: Replace block with line 2.
 if sys.version_info >= (3, 11):
@@ -29,7 +31,7 @@ def _locate_config_file() -> Path | None:
     return None
 
 
-def load_config() -> dict[str, Any] | None:
+def load_config() -> rendering.ConfigDict | None:
     """Load the configuration if config file or config entry in pyproject.toml exists.
 
     If neither config file was found or pyproject.toml file doesn't have
@@ -45,4 +47,4 @@ def load_config() -> dict[str, Any] | None:
 
     if config_path.name == "pyproject.toml":
         return config.get("tool", {}).get("griffe2md", None)
-    return config
+    return typing.cast(rendering.ConfigDict, config)

src/griffe2md/main.py

@@ -27,7 +27,7 @@ def _output(text: str, to: IO | str | None = None) -> None:
         to.write(text)
 
 
-def prepare_context(obj: Object, config: dict | None = None) -> dict:
+def prepare_context(obj: Object, config: rendering.ConfigDict | None = None) -> dict:
     """Prepare Jinja context.
 
     Parameters:
@@ -37,7 +37,7 @@ def prepare_context(obj: Object, config: dict | None = None) -> dict:
     Returns:
         The Jinja context.
     """
-    config = dict(rendering.default_config, **(config or {}))
+    config = rendering.ConfigDict(rendering.default_config, **(config or {}))
     if config["filters"]:
         config["filters"] = [(re.compile(filtr.lstrip("!")), filtr.startswith("!")) for filtr in config["filters"]]
 
@@ -113,7 +113,7 @@ def prepare_env(env: Environment | None = None) -> Environment:
     return env
 
 
-def render_object_docs(obj: Object, config: dict | None = None) -> str:
+def render_object_docs(obj: Object, config: rendering.ConfigDict | None = None) -> str:
     """Render docs for a given object.
 
     Parameters:
@@ -129,7 +129,7 @@ def render_object_docs(obj: Object, config: dict | None = None) -> str:
     return mdformat.text(rendered)
 
 
-def render_package_docs(package: str, config: dict | None = None) -> str:
+def render_package_docs(package: str, config: rendering.ConfigDict | None = None) -> str:
     """Render docs for a given package.
 
     Parameters:
@@ -147,7 +147,7 @@ def render_package_docs(package: str, config: dict | None = None) -> str:
     return render_object_docs(module, config)  # type: ignore[arg-type]
 
 
-def write_package_docs(package: str, config: dict | None = None, output: IO | str | None = None) -> None:
+def write_package_docs(package: str, config: rendering.ConfigDict | None = None, output: IO | str | None = None) -> None:
     """Write docs for a given package to a file or stdout.
 
     Parameters:

src/griffe2md/rendering.py

@@ -8,6 +8,7 @@
 import re
 import string
 import sys
+import typing
 from functools import lru_cache, partial
 from re import Pattern
 from typing import TYPE_CHECKING, Any, Callable
@@ -46,7 +47,54 @@ class Order(enum.Enum):
     """Source code order."""
 
 
-default_config: dict = {
+class ConfigDict(typing.TypedDict):
+    """Configuration for griffe2md, griffe and mkdocstrings"""
+
+    allow_inspection: bool
+    annotations_path: str
+    docstring_options: dict
+    """mkdocstring [configuration](https://mkdocstrings.github.io/python/usage/configuration/general/)"""
+
+    docstring_section_style: str
+    docstring_style: str
+    """Style of project docstring. Supported options are: 'auto', 'google', 'numpy' or 'sphinx'"""
+
+    filters: Any
+    group_by_category: bool
+    heading_level: int
+    inherited_members: bool
+    line_length: int
+    load_external_modules: bool
+    members: Any
+    members_order: Any
+    merge_init_into_class: bool
+    preload_modules: Any
+    separate_signature: bool
+    show_bases: bool
+    show_category_heading: bool
+    show_docstring_attributes: bool
+    show_docstring_description: bool
+    show_docstring_examples: bool
+    show_docstring_other_parameters: bool
+    show_docstring_parameters: bool
+    show_docstring_raises: bool
+    show_docstring_receives: bool
+    show_docstring_returns: bool
+    show_docstring_warns: bool
+    show_docstring_yields: bool
+    show_if_no_docstring: bool
+    show_object_full_path: bool
+    show_root_full_path: bool
+    show_root_heading: bool
+    show_root_members_full_path: bool
+    show_signature: bool
+    show_signature_annotations: bool
+    show_submodules: bool
+    signature_crossrefs: bool
+    summary: bool
+
+
+default_config: ConfigDict = {
     "docstring_style": "google",
     "docstring_options": {"ignore_init_summary": True},
     "show_root_heading": True,