Support for MkDocs and Google/NumPy docstring styles

[Borda]

🚀 Feature: Support for MkDocs (Admonitions) and Google/NumPy docstring styles

Is your feature request related to a problem? Please describe.

Currently, pyDeprecate injects warnings using ReStructuredText (RST) specific directives (e.g., .. deprecated::), as introduced in PR #31.

While this works perfectly for Sphinx, it creates issues for other common documentation stacks:

1. MkDocs / Markdown: The .. deprecated:: directive renders as a literal text block or broken code rather than a visual warning box.
2. Google/NumPy Style: These styles rely on strict section headers (e.g., Args:, Returns:). Appending a deprecation warning to the end of the docstring (or indiscriminately at the top) can break the parsing of these sections, causing arguments to not be documented at all in the generated site.

Describe the solution you'd like

I propose extending the deprecated decorator to support multiple docstring output formats, likely via a configuration option or global setting.

1. Support for MkDocs (Admonitions)
Instead of RST directives, allow outputting Markdown-native "Admonitions" (supported by mkdocs-material and standard Markdown parsers).

• Current Output: .. deprecated:: 1.0
• Proposed Output:

  !!! warning "Deprecated in 1.0"
      Use `new_func` instead.

2. Support for Google/NumPy Injection Strategy
Instead of appending the warning to the end of the docstring, the deprecation notice should be injected before the Args: (Google) or Parameters (NumPy) section to ensure parsers do not abort reading the docstring.

Describe alternatives you've considered

• Status Quo: Users of MkDocs must accept broken formatting in their API references.
• Manual Docstrings: Users manually write the deprecation notices, defeating the purpose of the automation provided by pyDeprecate.

Additional context

• Refers to PR add msg to docs #31 which added the initial Sphinx support.
• Relevant for users moving to modern stacks like mkdocstrings.