[](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/sections/installation).
## 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_html('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_html` 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 possible 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_html` 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": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "dash, plotly, markdown, flask",
"author": "emher",
"author_email": "emil.h.eriksen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a3/ca/39760f71285ca4ef5fd860d066ba1b4e96a224af966e2d03dbd2f59919c5/dash_down-0.1.4.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/sections/installation).\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_html('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_html` 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 possible 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_html` 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": null,
"version": "0.1.4",
"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": "bb2f3c62c1836867a1d156d2cbc751c470cfd6e2b31bfdf67db07bdc2d2034de",
"md5": "1fa152c75d35f4538773af3e7d2248fd",
"sha256": "e6001d2c897ae7b7277227d1f6831fa56ec534f9008d4ebac107c506683fced6"
},
"downloads": -1,
"filename": "dash_down-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1fa152c75d35f4538773af3e7d2248fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 9534,
"upload_time": "2024-11-26T11:22:13",
"upload_time_iso_8601": "2024-11-26T11:22:13.703656Z",
"url": "https://files.pythonhosted.org/packages/bb/2f/3c62c1836867a1d156d2cbc751c470cfd6e2b31bfdf67db07bdc2d2034de/dash_down-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a3ca39760f71285ca4ef5fd860d066ba1b4e96a224af966e2d03dbd2f59919c5",
"md5": "58e13fa40015bdba8b09086d4571198b",
"sha256": "3b927070072a0efe6ac3b5bcbdc7def4486def7c6e9c852a93f4964e53dbee5b"
},
"downloads": -1,
"filename": "dash_down-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "58e13fa40015bdba8b09086d4571198b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 9669,
"upload_time": "2024-11-26T11:22:15",
"upload_time_iso_8601": "2024-11-26T11:22:15.411513Z",
"url": "https://files.pythonhosted.org/packages/a3/ca/39760f71285ca4ef5fd860d066ba1b4e96a224af966e2d03dbd2f59919c5/dash_down-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-26 11:22:15",
"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
