# 🏳️⚧️ Transdoc 🏳️⚧️
A simple tool for transforming Python docstrings by embedding results from
Python function calls.
## Installation
`pip install transdoc`
## Usage
Creating transformation rules is as simple as defining Python functions.
```py
# rules.py
def my_rule() -> str:
'''
A simple rule for rewriting docstrings
'''
return f"This text was added by Transdoc!"
```
They can then be used by placing their name within `{{` double braces `}}` in
any docstring.
```py
# program.py
def say_hi(name: str) -> str:
'''
Says hello to someone.
{{my_rule}}
'''
return f"Hello, {name}!"
```
By executing `transdoc program.py -o program_transformed.py -r rules.py`,
Transdoc will produce a file `program_transformed.py` with the following
contents:
```py
# program.py
def say_hi(name: str) -> str:
'''
Says hello to someone.
This text was added by Transdoc!
'''
return f"Hello, {name}!"
```
Rules can be as complex as you need, accepting any number of arguments. You can
call them like you would call the original Python function.
```py
# rules.py
def repeat(text: str, n: int = 2) -> str:
'''
Repeat the given text any number of times.
'''
return " ".join([text for _ in range(n)])
```
Using this rule to transform the following code
```py
def say_hi(name: str) -> str:
'''
Says hello to someone.
{{repeat('wowee!')}}
{{repeat('WOWEE!', n=5)}}
'''
return f"Hello, {name}!"
```
will produce this result:
```py
def say_hi(name: str) -> str:
'''
Says hello to someone.
Wowee! Wowee!
WOWEE! WOWEE! WOWEE! WOWEE! WOWEE!
'''
return f"Hello, {name}!"
```
Since passing a single string as an argument is so common, Transdoc adds a
special syntax for this. Simply place the string argument in square brackets.
```py
def mdn_link(e: str) -> str:
'''
Return a Markdown-formatted link for an HTML element
'''
return (
f"[View <{e}> on MDN]"
f"(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/{e})"
)
```
Using this rule to transform the following code
```py
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>"
```
will produce this result:
```py
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>"
```
## Library usage
Transdoc also offers a simple library which can be used to perform these
operations programmatically.
```py
import transdoc
def fancy():
return "✨fancy✨"
def my_function():
'''Wow this is some {{fancy}} documentation'''
result = transdoc.transform(
my_function, # Code to transform
[fancy], # Rules to use in transformation (or a module containing rules)
)
# Result now contains a string with the transformed source code for my_function
```
## Integration with build systems
You can integrate Transdoc with project management systems and use it as a
pre-build script, so that your docstrings can be automatically built right
before packaging and distributing your project.
### Poetry
The system is undocumented and unstable, however it is possible (according to
[this GitHub comment](https://github.com/python-poetry/poetry/issues/5539#issuecomment-1126818974))
to get a pre-build script added.
In `pyproject.toml`:
```toml
[tool.poetry.build]
generate-setup-file = false
script = "build.py"
# ...
[build-system]
requires = ["poetry-core", "transdoc"]
build-backend = "poetry.core.masonry.api"
```
In a file `build.py`:
```py
import transdoc
exit(transdoc.main("src", "rules.py", "build_dir", force=True))
```
Raw data
{
"_id": null,
"home_page": "https://github.com/MaddyGuthridge/transdoc",
"name": "transdoc",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "documentation, source, transform, parse, pre-processor",
"author": "Maddy Guthridge",
"author_email": "hello@maddyguthridge.com",
"download_url": "https://files.pythonhosted.org/packages/13/5b/82e690b49d1fbf04d3f5cba09d01964e8925322c306deb4432fb23b345b5/transdoc-0.2.5.tar.gz",
"platform": null,
"description": "# \ud83c\udff3\ufe0f\u200d\u26a7\ufe0f Transdoc \ud83c\udff3\ufe0f\u200d\u26a7\ufe0f\n\nA simple tool for transforming Python docstrings by embedding results from\nPython function calls.\n\n## Installation\n\n`pip install transdoc`\n\n## Usage\n\nCreating transformation rules is as simple as defining Python functions.\n\n```py\n# rules.py\ndef my_rule() -> str:\n '''\n A simple rule for rewriting docstrings\n '''\n return f\"This text was added by Transdoc!\"\n```\n\nThey can then be used by placing their name within `{{` double braces `}}` in\nany docstring.\n\n```py\n# program.py\ndef say_hi(name: str) -> str:\n '''\n Says hello to someone.\n {{my_rule}}\n '''\n return f\"Hello, {name}!\"\n```\n\nBy executing `transdoc program.py -o program_transformed.py -r rules.py`,\nTransdoc will produce a file `program_transformed.py` with the following\ncontents:\n\n```py\n# program.py\ndef say_hi(name: str) -> str:\n '''\n Says hello to someone.\n This text was added by Transdoc!\n '''\n return f\"Hello, {name}!\"\n```\n\nRules can be as complex as you need, accepting any number of arguments. You can\ncall them like you would call the original Python function.\n\n```py\n# rules.py\ndef repeat(text: str, n: int = 2) -> str:\n '''\n Repeat the given text any number of times.\n '''\n return \" \".join([text for _ in range(n)])\n```\n\nUsing this rule to transform the following code\n\n```py\ndef say_hi(name: str) -> str:\n '''\n Says hello to someone.\n {{repeat('wowee!')}}\n {{repeat('WOWEE!', n=5)}}\n '''\n return f\"Hello, {name}!\"\n```\n\nwill produce this result:\n\n```py\ndef say_hi(name: str) -> str:\n '''\n Says hello to someone.\n Wowee! Wowee!\n WOWEE! WOWEE! WOWEE! WOWEE! WOWEE!\n '''\n return f\"Hello, {name}!\"\n```\n\nSince passing a single string as an argument is so common, Transdoc adds a\nspecial syntax for this. Simply place the string argument in square brackets.\n\n```py\ndef mdn_link(e: str) -> str:\n '''\n Return a Markdown-formatted link for an HTML element\n '''\n return (\n f\"[View <{e}> on MDN]\"\n f\"(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/{e})\"\n )\n```\n\nUsing this rule to transform the following code\n\n```py\ndef make_link(text: str, href: str) -> str:\n '''\n Generate an HTML link.\n {{mdn_link[a]}}\n '''\n # Please don't write code this insecure in real life\n return f\"<a href={href}>{text}</a>\"\n```\n\nwill produce this result:\n\n```py\ndef make_link(text: str, href: str) -> str:\n '''\n Generate an HTML link.\n [View <a> on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)\n '''\n # Please don't write code this insecure in real life\n return f\"<a href={href}>{text}</a>\"\n```\n\n## Library usage\n\nTransdoc also offers a simple library which can be used to perform these\noperations programmatically.\n\n```py\nimport transdoc\n\ndef fancy():\n return \"\u2728fancy\u2728\"\n\ndef my_function():\n '''Wow this is some {{fancy}} documentation'''\n\n\nresult = transdoc.transform(\n my_function, # Code to transform\n [fancy], # Rules to use in transformation (or a module containing rules)\n)\n# Result now contains a string with the transformed source code for my_function\n```\n\n## Integration with build systems\n\nYou can integrate Transdoc with project management systems and use it as a\npre-build script, so that your docstrings can be automatically built right\nbefore packaging and distributing your project.\n\n### Poetry\n\nThe system is undocumented and unstable, however it is possible (according to\n[this GitHub comment](https://github.com/python-poetry/poetry/issues/5539#issuecomment-1126818974))\nto get a pre-build script added.\n\nIn `pyproject.toml`:\n\n```toml\n[tool.poetry.build]\ngenerate-setup-file = false\nscript = \"build.py\"\n\n# ...\n\n[build-system]\nrequires = [\"poetry-core\", \"transdoc\"]\nbuild-backend = \"poetry.core.masonry.api\"\n```\n\nIn a file `build.py`:\n\n```py\nimport transdoc\n\nexit(transdoc.main(\"src\", \"rules.py\", \"build_dir\", force=True))\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple tool for transforming Python docstrings by embedding results from Python function calls",
"version": "0.2.5",
"project_urls": {
"Homepage": "https://github.com/MaddyGuthridge/transdoc",
"Repository": "https://github.com/MaddyGuthridge/transdoc"
},
"split_keywords": [
"documentation",
" source",
" transform",
" parse",
" pre-processor"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e3229acba3633cc63156b1e87c6eb528f8ad9b2af557e00a02a1e6fc95d57ee2",
"md5": "24b08aa8569d543d57b17507b0d8f678",
"sha256": "94ab2d87f97539b3f8dc235c0574335696dd27eae910b20a61a66dc7f0f8d25f"
},
"downloads": -1,
"filename": "transdoc-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "24b08aa8569d543d57b17507b0d8f678",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 15669,
"upload_time": "2024-08-17T06:46:24",
"upload_time_iso_8601": "2024-08-17T06:46:24.598843Z",
"url": "https://files.pythonhosted.org/packages/e3/22/9acba3633cc63156b1e87c6eb528f8ad9b2af557e00a02a1e6fc95d57ee2/transdoc-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "135b82e690b49d1fbf04d3f5cba09d01964e8925322c306deb4432fb23b345b5",
"md5": "775364d32396945aa9244168355d2b89",
"sha256": "a50c85a25faeaeb282fdee2f7d4b22a357c69a68c6bc950df7873e601f38a0ac"
},
"downloads": -1,
"filename": "transdoc-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "775364d32396945aa9244168355d2b89",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 12874,
"upload_time": "2024-08-17T06:46:26",
"upload_time_iso_8601": "2024-08-17T06:46:26.135626Z",
"url": "https://files.pythonhosted.org/packages/13/5b/82e690b49d1fbf04d3f5cba09d01964e8925322c306deb4432fb23b345b5/transdoc-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-17 06:46:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MaddyGuthridge",
"github_project": "transdoc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "transdoc"
}
JSON
