[](https://github.com/emilhe/dash-down/actions/workflows/python-test.yml)
[](https://codecov.io/gh/emilhe/dash-down)
The `dash-down` package provides tools to render markdown files into Plotly Dash component trees. Besides standard markdown syntax, a custom interpretation of the [directive syntax extension](https://mistune.readthedocs.io/en/latest/directives.html) makes it possible to embed Dash code blocks and/or applications (including callbacks). For a live demo, please take look at the [`dash-extensions` documentation](https://www.dash-extensions.com/getting-started/installation#a-example).
## Getting started
Make sure that you have setup [poetry](https://python-poetry.org/). Then run
poetry install
to install dependencies.
#### Running the example
poetry run python example.py
#### Running the tests
poetry run pytest
## Custom content
Custom content is rendered via the markdown [directive syntax extension](https://mistune.readthedocs.io/en/latest/directives.html). A directive has the following syntax,
.. directive-name:: directive value
:option-key: option value
:option-key: option value
full featured markdown text here
where the `directive-name` is mandatory, while the `value`, the `options` (specified as key value pairs), and the `text` are optional.
#### What directives are bundled?
Currently, the bundled directives are
* **api-doc** - a directive for rendering api documentation for a component
* **dash-proxy** - a directive for rendering dash apps (including interactivity)
#### How to create custom directives?
The easiest way to create a custom directive is to create a function with the following signature,
```python
from box import Box
from dash_extensions.enrich import DashBlueprint
def directive_name(value: str, text: str, options: Box[str, str], blueprint: DashBlueprint):
"""
:param value: the directive value (optional)
:param text: the markdown text (optional)
:param options: a Box object containing all key value pairs (optional)
:param blueprint: the DashBlueprint of the resulting Dash component tree, used e.g. for callback registration
:return: a Dash component
"""
...
```
Say, we want to make a new directive that yields a plot of the `iris` dataset. The code would then be along the lines of,
```python
import plotly.express as px
from box import Box
from dash_extensions.enrich import dcc, DashBlueprint
def graph(value: str, text: str, options: Box[str, str], blueprint: DashBlueprint):
df = getattr(px.data, options.dataset)()
fig = px.scatter(df, x=options.x, y=options.y)
return dcc.Graph(figure=fig)
```
With this directive defined, it is now possible to create a graph similar to [the one in the Dash docs](https://dash.plotly.com/dash-core-components/graph) with the following syntax,
.. graph::
:dataset: iris
:x: sepal_width
:y: sepal_length
To render a markdown file using the new, shiny directive, the syntax would be,
```python
from dash_extensions.enrich import DashProxy
from dash_down.express import md_to_blueprint_dmc, GITHUB_MARKDOWN_CSS_LIGHT
...
blueprint = md_to_blueprint_dmc('path_to_your_md_file', directives=[graph])
app = DashProxy(blueprint=blueprint, external_stylesheets=[GITHUB_MARKDOWN_CSS_LIGHT])
if __name__ == '__main__':
app.run_server()
```
A working example is bundled in the repo (see `example_custom_directive.py`).
#### How to customize the layout of the rendered blueprint?
The layout of the blueprint returned by the renderer can be customized by passing a custom app shell via the `shell` keyword of the `md_to_blueprint_dmc` function. A working example is bundled in the repo (see `example_code_renderer.py`).
Per default, the app shell is a `Div` element with `className="markdown-body"`. This class makes it possibly to use GitHub CSS for styling.
#### How to customize the way code is rendered with the DashProxyDirective?
The layout of the Dash apps rendered via the `DashProxyDirective` can be customized via the `dash_proxy_shell` keyword of the `md_to_blueprint_dmc` function. A working example is bundled in the repo (see `example_code_renderer.py`).
Per default, the app shell `Div` element with the code rendered as the first child and the resulting app rendered as the second.
#### How to customize the markdown rendering itself?
Make a subclass of `DashMantineRenderer` (or `DashHtmlRenderer`, if you prefer to start from raw HTML) and override the render function(s) for any element that you want to change. A good place to start would be to look at the `DashMantineRenderer` class itself for inspiration.
Raw data
{
"_id": null,
"home_page": "https://github.com/emilhe/dash-down",
"name": "dash-down",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "dash,plotly,markdown,flask",
"author": "emher",
"author_email": "emil.h.eriksen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fa/82/5ef4fd565f933c3ed6be661117fbfb0a0e6b20106674efc7d7663cc573d4/dash_down-0.1.2.tar.gz",
"platform": null,
"description": "[](https://github.com/emilhe/dash-down/actions/workflows/python-test.yml)\n[](https://codecov.io/gh/emilhe/dash-down)\n\nThe `dash-down` package provides tools to render markdown files into Plotly Dash component trees. Besides standard markdown syntax, a custom interpretation of the [directive syntax extension](https://mistune.readthedocs.io/en/latest/directives.html) makes it possible to embed Dash code blocks and/or applications (including callbacks). For a live demo, please take look at the [`dash-extensions` documentation](https://www.dash-extensions.com/getting-started/installation#a-example).\n\n## Getting started\n\nMake sure that you have setup [poetry](https://python-poetry.org/). Then run\n\n poetry install\n\nto install dependencies.\n\n#### Running the example\n\n poetry run python example.py\n\n#### Running the tests\n\n poetry run pytest\n\n## Custom content\n\nCustom content is rendered via the markdown [directive syntax extension](https://mistune.readthedocs.io/en/latest/directives.html). A directive has the following syntax,\n\n .. directive-name:: directive value\n :option-key: option value\n :option-key: option value\n \n full featured markdown text here\n\nwhere the `directive-name` is mandatory, while the `value`, the `options` (specified as key value pairs), and the `text` are optional. \n\n#### What directives are bundled?\n\nCurrently, the bundled directives are\n\n* **api-doc** - a directive for rendering api documentation for a component\n* **dash-proxy** - a directive for rendering dash apps (including interactivity)\n\n#### How to create custom directives?\n\nThe easiest way to create a custom directive is to create a function with the following signature,\n\n```python\nfrom box import Box\nfrom dash_extensions.enrich import DashBlueprint\n\ndef directive_name(value: str, text: str, options: Box[str, str], blueprint: DashBlueprint):\n \"\"\"\n :param value: the directive value (optional)\n :param text: the markdown text (optional)\n :param options: a Box object containing all key value pairs (optional)\n :param blueprint: the DashBlueprint of the resulting Dash component tree, used e.g. for callback registration\n :return: a Dash component\n \"\"\"\n ...\n```\n\nSay, we want to make a new directive that yields a plot of the `iris` dataset. The code would then be along the lines of,\n\n```python\nimport plotly.express as px\nfrom box import Box\nfrom dash_extensions.enrich import dcc, DashBlueprint\n\ndef graph(value: str, text: str, options: Box[str, str], blueprint: DashBlueprint):\n df = getattr(px.data, options.dataset)()\n fig = px.scatter(df, x=options.x, y=options.y)\n return dcc.Graph(figure=fig)\n```\n\nWith this directive defined, it is now possible to create a graph similar to [the one in the Dash docs](https://dash.plotly.com/dash-core-components/graph) with the following syntax,\n\n .. graph::\n :dataset: iris\n :x: sepal_width\n :y: sepal_length\n\nTo render a markdown file using the new, shiny directive, the syntax would be,\n\n```python\nfrom dash_extensions.enrich import DashProxy\nfrom dash_down.express import md_to_blueprint_dmc, GITHUB_MARKDOWN_CSS_LIGHT\n\n...\n\nblueprint = md_to_blueprint_dmc('path_to_your_md_file', directives=[graph])\napp = DashProxy(blueprint=blueprint, external_stylesheets=[GITHUB_MARKDOWN_CSS_LIGHT])\n\nif __name__ == '__main__':\n app.run_server()\n```\n\nA working example is bundled in the repo (see `example_custom_directive.py`).\n\n#### How to customize the layout of the rendered blueprint?\n\nThe layout of the blueprint returned by the renderer can be customized by passing a custom app shell via the `shell` keyword of the `md_to_blueprint_dmc` function. A working example is bundled in the repo (see `example_code_renderer.py`).\n\nPer default, the app shell is a `Div` element with `className=\"markdown-body\"`. This class makes it possibly to use GitHub CSS for styling.\n\n#### How to customize the way code is rendered with the DashProxyDirective?\n\nThe layout of the Dash apps rendered via the `DashProxyDirective` can be customized via the `dash_proxy_shell` keyword of the `md_to_blueprint_dmc` function. A working example is bundled in the repo (see `example_code_renderer.py`).\n\nPer default, the app shell `Div` element with the code rendered as the first child and the resulting app rendered as the second.\n\n#### How to customize the markdown rendering itself?\n\nMake a subclass of `DashMantineRenderer` (or `DashHtmlRenderer`, if you prefer to start from raw HTML) and override the render function(s) for any element that you want to change. A good place to start would be to look at the `DashMantineRenderer` class itself for inspiration.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/emilhe/dash-down",
"Homepage": "https://github.com/emilhe/dash-down",
"Repository": "https://github.com/emilhe/dash-down"
},
"split_keywords": [
"dash",
"plotly",
"markdown",
"flask"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8aa5bbfe3745b75361cf9009437751e615949c4c29e84c65550f89fb12d81f48",
"md5": "9e10a40994f43a7242bbe18065ab8f23",
"sha256": "fc850eebc0d3d5c137bec098b4f720131705bd61be8a52d66a15687831c20161"
},
"downloads": -1,
"filename": "dash_down-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e10a40994f43a7242bbe18065ab8f23",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 9348,
"upload_time": "2023-08-24T10:12:23",
"upload_time_iso_8601": "2023-08-24T10:12:23.426528Z",
"url": "https://files.pythonhosted.org/packages/8a/a5/bbfe3745b75361cf9009437751e615949c4c29e84c65550f89fb12d81f48/dash_down-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fa825ef4fd565f933c3ed6be661117fbfb0a0e6b20106674efc7d7663cc573d4",
"md5": "e63d916deed45d6acf646602856f2c27",
"sha256": "bd74409485be2f5fb258e23996814ec3f46b46a354d88b64b24bcfa6a1d04c18"
},
"downloads": -1,
"filename": "dash_down-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "e63d916deed45d6acf646602856f2c27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 9490,
"upload_time": "2023-08-24T10:12:24",
"upload_time_iso_8601": "2023-08-24T10:12:24.655300Z",
"url": "https://files.pythonhosted.org/packages/fa/82/5ef4fd565f933c3ed6be661117fbfb0a0e6b20106674efc7d7663cc573d4/dash_down-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-24 10:12:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "emilhe",
"github_project": "dash-down",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dash-down"
}
JSON
