Metadata-Version: 2.3
Name: transdoc-python
Version: 0.1.5
Summary: A Transdoc handler for Python docstrings
Author: Maddy Guthridge
Author-email: Maddy Guthridge <hello@maddyguthridge.com>
License: MIT
Requires-Dist: libcst>=1.6.0,<2.0.0
Requires-Dist: transdoc>=1.0.0,<2.0.0
Requires-Python: >=3.11
Project-URL: homepage, https://maddyguthridge.github.io/transdoc/handlers/python
Project-URL: repository, https://github.com/MaddyGuthridge/transdoc
Project-URL: documentation, https://maddyguthridge.github.io/transdoc/handlers/python
Project-URL: Bug Tracker, https://github.com/MaddyGuthridge/transdoc/issues
Description-Content-Type: text/markdown

# 🏳️‍⚧️🐍 Transdoc Python

A Transdoc handler for Python docstrings.

## Installation

```sh
# Use your dependency manager of choice
uv add transdoc[python]
poetry add transdoc[python]
pip install transdoc[python]
```

## Usage

Transdoc rules are applied to Python docstrings.

For example, given the following rule:

```py
def mdn_link(e: str) -> str:
    '''
    Return a Markdown-formatted link to MDN's documentation of an HTML element.
    '''
    return (
        f"[View `<{e}>` on MDN]"
        f"(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/{e})"
    )
```

The following Python function's docstring would be transformed as follows:

```py
# Before
def make_link(text: str, href: str) -> str:
    '''
    Generate an HTML link.
    {{mdn_link[a]}}
    '''
    # Please don't write code this insecure in real life
    return f"<a href={href}>{text}</a>"

# After
def make_link(text: str, href: str) -> str:
    '''
    Generate an HTML link.
    [View `<a>` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)
    '''
    # Please don't write code this insecure in real life
    return f"<a href={href}>{text}</a>"
```
