Decorators

.mypy.ini

@@ -0,0 +1,5 @@
+[mypy]
+strict = True
+
+[mypy-griffe.*]
+ignore_missing_imports = True

.pre-commit-config.yaml

@@ -12,12 +12,12 @@ repos:
   - id: check-symlinks
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.8
+  rev: v0.3.0
   hooks:
     - id: ruff
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.8
+  rev: v0.3.0
   hooks:
     - id: ruff-format
 
@@ -39,15 +39,13 @@ repos:
       ]
 
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.7.1
+  rev: v1.8.0
   hooks:
     - id: mypy
-      exclude: ^(tests/|setup\.py)
-      args:
-        - --strict
+      exclude: ^tests|src/docstring_inheritance/griffe\.py$\a
 
 - repo: https://github.com/Lucas-C/pre-commit-hooks
-  rev: v1.5.4
+  rev: v1.5.5
   hooks:
     - id: insert-license
       name: insert MIT license

.ruff.toml

@@ -3,6 +3,8 @@ unsafe-fixes = true
 preview = true
 target-version = "py38"
 src = ["src"]
+
+[lint]
 task-tags = ["TODO"]
 ignore = [
     # Conflicts with ruff format.
@@ -48,8 +50,10 @@ select = [
     "N",
     "T",
     "W",
+    "EM",
     "UP",
     "PT",
+#    "ANN",
     "FLY",
     "ISC",
     "LOG",
@@ -68,19 +72,21 @@ select = [
     "SLOT",
     "FURB",
     "PERF",
+    "TRIO",
 #    "C",
 #    "D",
 #    "S",
 #    "PL",
+#    "PD",
 #    "BLE",
 #    "FBT",
 ]
 
-[isort]
+[lint.isort]
 force-single-line = true
 
-[pydocstyle]
+[lint.pydocstyle]
 convention = "google"
 
-[per-file-ignores]
+[lint.per-file-ignores]
 "tests/*.py" = ["D", "PT009","PT011", "PT027", "PTH"]

CHANGELOG.md

@@ -13,9 +13,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2024-03
+### Added
+- Extension to support building docs with mkdocs.
+### Fixed
+- Docstrings inheritance with decorators.
+
 ## [2.1.2] - 2023-12
 ### Fixed
-- Warning messages are no longer shown by default. 
+- Warning messages are no longer shown by default.
   Set the environment variable `DOCSTRING_INHERITANCE_WARNS` to activate them.
 
 ## [2.1.1] - 2023-12

README.md

@@ -10,7 +10,6 @@
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/docstring-inheritance)
 ![PyPI](https://img.shields.io/pypi/v/docstring-inheritance)
 ![Conda (channel only)](https://img.shields.io/conda/vn/conda-forge/docstring-inheritance)
-![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)
 ![Codecov branch](https://img.shields.io/codecov/c/gh/AntoineD/docstring-inheritance/main)
 
 `docstring-inheritance` is a python package to avoid writing and maintaining duplicated python docstrings.
@@ -30,7 +29,7 @@ such that its derived classes fully or partly inherit the docstrings.
   the signature arguments are inherited individually.
 - Minimum performance cost: the inheritance is performed at import time,
   not for each call.
-- Compatible with rendering the documentation with [Sphinx](http://www.sphinx-doc.org/).
+- Compatible with rendering the documentation with [Sphinx](http://www.sphinx-doc.org/) and [mkdocs](https://www.mkdocs.org/) (See [below](#mkdocs)).
 - Missing docstring sections for signature arguments can be notified by warnings
   when the environment variable `DOCSTRING_INHERITANCE_WARNS` is set.
 - Docstring sections can be compared to detect duplicated or similar contents that could be inherited.
@@ -365,6 +364,24 @@ the docstring sections are considered similar.
 Use a ratio of `1` to detect identical docstring sections.
 Use a ratio lower than `1` to detect similar docstring sections.
 
+# Mkdocs
+
+To render the documentation with `mkdocs`,
+the package `mkdocstring[python]` is required and
+the package `griffe-inherited-docstrings` is recommended,
+finally the following shall be added to `mkdocs.yml`:
+
+```yaml
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          extensions:
+            - griffe_inherited_docstrings
+            - docstring_inheritance.griffe
+```
+
 # Similar projects
 
 [custom_inherit](https://github.com/rsokl/custom_inherit):

pyproject.toml

@@ -1,7 +1,3 @@
-[build-system]
-requires = ["setuptools", "setuptools_scm"]
-build-backend = "setuptools.build_meta"
-
 [project]
 name = "docstring-inheritance"
 dynamic = ["version"]
@@ -39,3 +35,7 @@ Source = "https://github.com/AntoineD/docstring-inheritance"
 Tracker = "https://github.com/AntoineD/docstring-inheritance/issues"
 
 [tool.setuptools_scm]
+
+[build-system]
+requires = ["setuptools", "setuptools_scm"]
+build-backend = "setuptools.build_meta"

requirements/test.txt

@@ -6,7 +6,7 @@
 #
 covdefaults==2.3.0
     # via docstring-inheritance (pyproject.toml)
-coverage[toml]==7.3.2
+coverage[toml]==7.4.3
     # via
     #   covdefaults
     #   pytest-cov
@@ -16,9 +16,9 @@ iniconfig==2.0.0
     # via pytest
 packaging==23.2
     # via pytest
-pluggy==1.3.0
+pluggy==1.4.0
     # via pytest
-pytest==7.4.3
+pytest==8.1.0
     # via
     #   docstring-inheritance (pyproject.toml)
     #   pytest-cov

src/docstring_inheritance/class_docstrings_inheritor.py

@@ -138,7 +138,7 @@ def _inherit_attrs_docstrings(
                         # the MRO for methods,
                         # we inherit only from the first found parent.
                         break
-                    # TODO: else WARN that no dosctring is defined and
+                    # TODO: else WARN that no docstring is defined and
                     # none can be inherited.
 
     @staticmethod

src/docstring_inheritance/docstring_inheritors/bases/inheritor.py

@@ -22,9 +22,13 @@
 from __future__ import annotations
 
 import difflib
-import inspect
 import os
 import warnings
+from inspect import getfile
+from inspect import getfullargspec
+from inspect import getmodule
+from inspect import getsourcelines
+from inspect import unwrap
 from textwrap import indent
 from typing import TYPE_CHECKING
 from typing import Any
@@ -58,12 +62,14 @@ def get_similarity_ratio(env_ratio: str | None) -> float:
     try:
         ratio = float(env_ratio)
     except ValueError:
-        raise ValueError(
+        msg = (
             "The docstring inheritance similarity ratio cannot be determined from "
             f"'{env_ratio}'."
-        ) from None
+        )
+        raise ValueError(msg) from None
     if not (0.0 <= ratio <= 1.0):
-        raise ValueError("The docstring inheritance similarity ratio must be in [0,1].")
+        msg = "The docstring inheritance similarity ratio must be in [0,1]."
+        raise ValueError(msg)
     return ratio
 
 
@@ -128,7 +134,10 @@ def _inherit(self, parent_doc: str) -> None:
             parent_sections,
             child_sections,
         )
-        self.__child_func.__doc__ = self._DOCSTRING_RENDERER.render(child_sections)
+        # Get the original function eventually behind decorators.
+        unwrap(self.__child_func).__doc__ = self._DOCSTRING_RENDERER.render(
+            child_sections
+        )
 
     def _warn_similar_sections(
         self,
@@ -200,13 +209,13 @@ def _warn(self, section_path: str, msg: str) -> None:
             msg: The warning message.
         """
         msg = f"in {self.__child_func.__qualname__}: section {section_path}: {msg}"
-        module = inspect.getmodule(self.__child_func)
+        module = getmodule(self.__child_func)
         module_name = module.__name__ if module is not None else None
         warnings.warn_explicit(
             msg,
             DocstringInheritanceWarning,
-            inspect.getfile(self.__child_func),
-            inspect.getsourcelines(self.__child_func)[1],
+            getfile(self.__child_func),
+            getsourcelines(self.__child_func)[1],
             module=module_name,
         )
 
@@ -311,7 +320,7 @@ def _filter_args_section(
         Returns:
             The section items filtered with the function signature.
         """
-        full_arg_spec = inspect.getfullargspec(self.__child_func)
+        full_arg_spec = getfullargspec(self.__child_func)
 
         all_args = full_arg_spec.args
         if "self" in all_args:

src/docstring_inheritance/docstring_inheritors/bases/parser.py

@@ -22,6 +22,7 @@
 from __future__ import annotations
 
 import inspect
+import operator
 import re
 import sys
 from abc import ABC
@@ -115,7 +116,7 @@ def _get_section_body(
             The docstring of a section.
         """
         reversed_section_body_lines = list(
-            dropwhile(lambda x: not x, reversed_section_body_lines)
+            dropwhile(operator.not_, reversed_section_body_lines)
         )
         reversed_section_body_lines.reverse()
         return "\n".join(reversed_section_body_lines)