Borda/pyDeprecate: Extended Docstring Tooling

🎉 pyDeprecate 0.7.0 pyDeprecate 0.7.0 is the docstring tooling release — deprecation notices now flow directly into rendered documentation. update_docstring=True is smarter (section-aware, per-argument) and MkDocs admonitions are supported alongside Sphinx. Two optional extensions wire up MKdocs and Sphinx autodoc so they pick up the injected notices automatically. 🚀 Added MkDocs / Markdown Admonition Output. @deprecated now accepts docstring_style="mkdocs" (alias: "markdown"). When update_docstring=True, the deprecation notice is injected as a !!! warning admonition instead of a Sphinx .. deprecated:: directive. Use docstring_style="auto" to detect the style automatically from existing docstring content. (#134) from deprecate import deprecated def new_load(path: str) -> dict: ... @deprecated(target=new_load, deprecated_in="0.7", remove_in="1.0", update_docstring=True, docstring_style="mkdocs") def load_config(path: str) -> dict: """Load the configuration file. Args: path: Path to the YAML config. """ # Resulting __doc__: # !!! warning "Deprecated in 0.7" # Will be removed in v1.0. Use `new_load` instead. # # Load the configuration file. # ... Section-Aware Google / NumPy Docstring Injection. update_docstring=True now detects Google-style (Args:, Returns:, …) and NumPy-style (Parameters, Returns + underline) section headers and inserts the deprecation notice before the first section rather than appending it at the end. (#134) @deprecated(target=new_fn, deprecated_in="0.7", remove_in="1.0", update_docstring=True) def old_fn(x: int) -> int: """Compute the result. Args: ← notice injected above this line x: Input value. """ Inline Argument Deprecation in Docstrings. When args_mapping is set and update_docstring=True, each renamed or removed argument is annotated directly in the Args: / :param section of the docstring rather than appending a general notice at the end. (#136) @deprecated( target=new_fn, deprecated_in="0.7", remove_in="1.0", args_mapping={"old_name": "new_name"}, update_docstring=True ) def old_fn(old_name: str) -> str: """Process a value. Args: old_name: The value to process. Deprecated since v0.7 — use `new_name` instead. Will be removed in v1.0. """ Griffe Extension for mkdocstrings (beta). Ensures that mkdocstrings renders the live injected docstring rather than the original source text. (#134) # mkdocs.yml plugins: - mkdocstrings: handlers: python: extensions: - deprecate.docstring.griffe_ext:RuntimeDocstrings Sphinx Autodoc Extension for Deprecated Classes (beta). Ensures that Sphinx autodoc renders deprecated class aliases with the correct members, signature, and injected .. deprecated:: notice. (#134) # conf.py extensions = [ "sphinx.ext.autodoc", "deprecate.docstring.sphinx_ext", ] Live Demo Documentation. The project now ships live demo documentation published to GitHub Pages — an MkDocs demo, a Sphinx demo, and a portal landing page linking to both. (#134, #137) 📦 Installation pip install --upgrade pyDeprecate 🙏 Thank You A big thank you to everyone who helped with this release: Jirka Borovec (@Borda) — architecture, review, and release management Automated contributions: @copilot-swe-agent[bot], @pre-commit-ci[bot], @github-advanced-security[bot], @Copilot Full Changelog: https://github.com/Borda/pyDeprecate/compare/v0.6.0.post0...v0.7.0