| Name | plumkdocs JSON |
| Version |
0.0.5
JSON |
| download |
| home_page | |
| Summary | Hacky mkdocs documentation for plum-dispatch |
| upload_time | 2023-11-24 17:28:06 |
| maintainer | |
| docs_url | None |
| author | Antonio Stanziola |
| requires_python | >=3.9,<4.0 |
| license | LGPL-3.0-only |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pluMkdocs
A very, very hacky way to document multiple dispatch function implemented using the wonderful [plum](https://github.com/beartype/plum) package
## ⚠️ Desclaimer
Have I mentioned that this is very hacky? It raises a whole lot of warnings, the vast majority of which I don't understand. Also, it is not heavly tested and only checked against mkdocs-material. It contains a lot of hard coded stuff and is not very flexible. It is also not very well documented.
I'm uploading this with the hope that someone will find it useful and will improve it. **Contributions welcome** :)
Also, I need this as a dependency for other projects, so I will probably not be able to maintain this very well.
## How to use
For a quickstart, check out the example in `example_module` and the `index.md` page in the `docs` folder. To see it in action, `cd` into `example_module` and run `mkdocs serve`.
The source code contains something like this:
```python
# Define some function to test
@dispatch.abstract
def foo(a, b):
"""Base description of the generic `foo` function"""
pass
@dispatch
def foo(a: int, b: int):
"""Add two integers.
Args:
a (int): First integer.
b (int): Second integer.
Returns:
int: Sum of a and b.
"""
return a + b
@dispatch
def foo(a: str, b: str):
"""Concatenate two strings.
Args:
a (str): First string.
b (str): Second string.
Returns:
str: Concatenation of a and b.
"""
return a + b
...
```
You should see something like this in the documentation:
#### More details
This package exposes an `implementations` macro that can be used to list the dispatched implementations of a function in your mkdocs.
To use it, in your `mkdocs.yml` file, make sure to load the `mkdocs-macros` plugin using
```yaml
plugins:
macros:
module_name: docs/macros
```
where `docs/macros` can be any path to a module that contains the macros. Then, in your `docs/macros.py` file, you can define the macros you want to use. If you don't have any other macro, you simply need to expose the function `define_env` from the `plumkdocs` module, like so:
```python
from plumkdocs import define_env
__all__ = ['define_env']
```
If you have other macros, you can simply add the macro to your `define_env` function, like so:
```python
from plumkdocs import mod_to_string
def define_env(env):
@env.macro
def implementations(module: str, function=None):
return mod_to_string(module, function)
```
In both cases, you can then use the `implementations` macro in your markdown files, like so:
```markdown
... some markdown ...
{{ implementations('my_package', 'foo') }}
... some more markdown ...
```
This will list all the implementations of the `foo` function in the `my_package` module. The docstrings will be (hopefully) correctly formatted, and the code will be highlighted using the `pygments` syntax highlighter. The signature of each method will also be displayed.
## Examples
To see a working example, check out the [`jaxdf`](https://ucl-bug.github.io/jaxdf/) and [`jwave`](https://ucl-bug.github.io/jwave/) documentation.
Raw data
{
"_id": null,
"home_page": "",
"name": "plumkdocs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Antonio Stanziola",
"author_email": "stanziola.antonio@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2c/a2/c002a34ea1d22c8fd2ae352af3201a9ad20245c04273fc93212ec7c613f4/plumkdocs-0.0.5.tar.gz",
"platform": null,
"description": "# pluMkdocs\n\nA very, very hacky way to document multiple dispatch function implemented using the wonderful [plum](https://github.com/beartype/plum) package\n\n## \u26a0\ufe0f Desclaimer\n\nHave I mentioned that this is very hacky? It raises a whole lot of warnings, the vast majority of which I don't understand. Also, it is not heavly tested and only checked against mkdocs-material. It contains a lot of hard coded stuff and is not very flexible. It is also not very well documented.\n\nI'm uploading this with the hope that someone will find it useful and will improve it. **Contributions welcome** :)\n\nAlso, I need this as a dependency for other projects, so I will probably not be able to maintain this very well.\n\n## How to use\n\nFor a quickstart, check out the example in `example_module` and the `index.md` page in the `docs` folder. To see it in action, `cd` into `example_module` and run `mkdocs serve`. \n\nThe source code contains something like this:\n\n```python\n# Define some function to test\n@dispatch.abstract\ndef foo(a, b):\n \"\"\"Base description of the generic `foo` function\"\"\"\n pass\n\n@dispatch\ndef foo(a: int, b: int):\n \"\"\"Add two integers.\n\n Args:\n a (int): First integer.\n b (int): Second integer.\n \n Returns:\n int: Sum of a and b.\n \"\"\"\n return a + b\n\n@dispatch\ndef foo(a: str, b: str):\n \"\"\"Concatenate two strings.\n\n Args:\n a (str): First string.\n b (str): Second string.\n \n Returns:\n str: Concatenation of a and b.\n \"\"\"\n return a + b\n\n...\n\n```\n\nYou should see something like this in the documentation:\n\n\n\n#### More details\n\nThis package exposes an `implementations` macro that can be used to list the dispatched implementations of a function in your mkdocs.\n\nTo use it, in your `mkdocs.yml` file, make sure to load the `mkdocs-macros` plugin using\n\n```yaml\nplugins:\n macros:\n module_name: docs/macros\n```\n\nwhere `docs/macros` can be any path to a module that contains the macros. Then, in your `docs/macros.py` file, you can define the macros you want to use. If you don't have any other macro, you simply need to expose the function `define_env` from the `plumkdocs` module, like so:\n\n```python\nfrom plumkdocs import define_env\n\n__all__ = ['define_env']\n```\n\nIf you have other macros, you can simply add the macro to your `define_env` function, like so:\n\n```python\nfrom plumkdocs import mod_to_string\n\ndef define_env(env):\n @env.macro\n def implementations(module: str, function=None):\n return mod_to_string(module, function)\n```\n\nIn both cases, you can then use the `implementations` macro in your markdown files, like so:\n\n```markdown\n... some markdown ...\n\n{{ implementations('my_package', 'foo') }}\n\n... some more markdown ...\n```\n\nThis will list all the implementations of the `foo` function in the `my_package` module. The docstrings will be (hopefully) correctly formatted, and the code will be highlighted using the `pygments` syntax highlighter. The signature of each method will also be displayed.\n\n## Examples\n\nTo see a working example, check out the [`jaxdf`](https://ucl-bug.github.io/jaxdf/) and [`jwave`](https://ucl-bug.github.io/jwave/) documentation.\n\n",
"bugtrack_url": null,
"license": "LGPL-3.0-only",
"summary": "Hacky mkdocs documentation for plum-dispatch",
"version": "0.0.5",
"project_urls": {
"Bug Tracker": "https://github.com/astanziola/plumkdocs/issues",
"Homepage": "https://github.com/astanziola/plumkdocs"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b805ca259054176f99504afba24d75aff799c5e1957cd5562a160598825845c8",
"md5": "49e284dfd41d4734ed5ae293ff73707b",
"sha256": "9d17f518b96e5ba4e0e2f9d766598eee588221c2ad18eda123502a1c7535a968"
},
"downloads": -1,
"filename": "plumkdocs-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "49e284dfd41d4734ed5ae293ff73707b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 6504,
"upload_time": "2023-11-24T17:28:03",
"upload_time_iso_8601": "2023-11-24T17:28:03.654915Z",
"url": "https://files.pythonhosted.org/packages/b8/05/ca259054176f99504afba24d75aff799c5e1957cd5562a160598825845c8/plumkdocs-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2ca2c002a34ea1d22c8fd2ae352af3201a9ad20245c04273fc93212ec7c613f4",
"md5": "9ea9fd299a7009f6917dd4f5d9c77c23",
"sha256": "ac12fdb1501d79d2100f60a23a5ab868e976e5f8df473a6862a7ccfcb17db481"
},
"downloads": -1,
"filename": "plumkdocs-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "9ea9fd299a7009f6917dd4f5d9c77c23",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 5880,
"upload_time": "2023-11-24T17:28:06",
"upload_time_iso_8601": "2023-11-24T17:28:06.185360Z",
"url": "https://files.pythonhosted.org/packages/2c/a2/c002a34ea1d22c8fd2ae352af3201a9ad20245c04273fc93212ec7c613f4/plumkdocs-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-24 17:28:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "astanziola",
"github_project": "plumkdocs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "plumkdocs"
}
