docs: add API docs

Author: Terseus

docs/api/adapters.md

@@ -0,0 +1,3 @@
+# Adapters module
+
+::: logging_with_context.adapters

docs/api/filters.md

@@ -0,0 +1,3 @@
+# Filters module
+
+::: logging_with_context.filters

docs/api/formatters.md

@@ -0,0 +1,3 @@
+# Formatters module
+
+::: logging_with_context.formatters

docs/api/global_context.md

@@ -0,0 +1,3 @@
+# Global context module
+
+::: logging_with_context.global_context

docs/api/index.md

@@ -0,0 +1,6 @@
+# API
+
+::: logging_with_context.adapters
+    options:
+      show_source: false
+      heading_level: 2

mkdocs.yml

@@ -34,3 +34,14 @@ markdown_extensions:
   - pymdownx.snippets
   # Allow nesting fences, needed for syntax highlight.
   - pymdownx.superfences
+plugins:
+  - mkdocstrings:
+      default_handler: python
+nav:
+  - Introduction: index.md
+  - howto.md
+  - API:
+    - api/global_context.md
+    - api/adapters.md
+    - api/formatters.md
+    - api/filters.md

pyproject.toml

@@ -23,6 +23,7 @@ dev = [
 ]
 doc = [
     "mkdocs-material>=9.5.49",
+    "mkdocstrings[python]>=0.27.0",
 ]
 
 [tool.hatch.version]

src/logging_with_context/adapters.py

@@ -15,28 +15,30 @@ class ContextualAdapter(LoggerAdapter):
 
     Example usage:
 
-        Set up everything
-
-        >>> import logging
-        >>> from logging_with_context.adapters import ContextualAdapter
-        >>> from logging_with_context.formatters import ExtraTextFormatter
-        >>> logging.basicConfig(level=logging.INFO)
-        >>> root = logging.getLogger()
-
-        To be able to see the context in the interpreter.
-
-        >>> root.handlers[0].setFormatter(
-        ...     ExtraTextFormatter(parent=root.handlers[0].formatter)
-        ... )
-
-        Using the adapter
-
-        >>> adapter = ContextualAdapter(root)
-        >>> with adapter.context({"key": "value"}) as logger:
-        ...     logger.info("This contains context")
-        ...     root.info("This does not")
-        INFO:root:This contains context |key="value"|
-        INFO:root:This does not
+    ```pycon
+    # Set up everything
+
+    >>> import logging
+    >>> from logging_with_context.adapters import ContextualAdapter
+    >>> from logging_with_context.formatters import ExtraTextFormatter
+    >>> logging.basicConfig(level=logging.INFO)
+    >>> root = logging.getLogger()
+
+    # To be able to see the context in the interpreter.
+
+    >>> root.handlers[0].setFormatter(
+    ...     ExtraTextFormatter(parent=root.handlers[0].formatter)
+    ... )
+
+    # Using the adapter
+
+    >>> adapter = ContextualAdapter(root)
+    >>> with adapter.context({"key": "value"}) as logger:
+    ...     logger.info("This contains context")
+    ...     root.info("This does not")
+    INFO:root:This contains context |key="value"|
+    INFO:root:This does not
+    ```
     """
 
     # NOTE: Override the type because Mapping doesn't support union operator

src/logging_with_context/filters.py

@@ -10,13 +10,16 @@
 class FilterWithContextVar(Filter):
     """
     Add the values from the current context to all the log messages as `extra` keys.
+
+    This class is not meant to be used directly, instead it's used by the
+    `global_context` module.
     """
 
     _context_var: ContextVar[dict[str, Any]]
 
     def __init__(self, context_var: ContextVar[dict[str, Any]]) -> None:
         """
-        Constructor..
+        Constructor.
 
         Parameters:
             context_var: The context storage to use.