# nb_js_diagrammers
IPython magics for rendering diagrams from simple scripts in Jupyter notebooks using various JavaScript diagram generators.
Simple magics for rendering diagrams from line and cell magics using the following JavaScript diagram generators:
- [Mermaid.js](https://mermaid-js.github.io/mermaid/#/): a wide variety of diagram types, including flowcharts, sequence diagrams, entity relationship diagrams
- [flowchart.js](http://flowchart.js.org/): flowchart generator
- [wavedrom](https://github.com/wavedrom/wavedrom): timing diagram generator
- [waversurfer.js](https://wavesurfer-js.org/): audio waveform visualisation
## Installation
Install from PyPi as: `pip install --upgrade nb-js-diagrammers`
Install direct from this repository as:
`pip install --upgrade git+https://github.com/innovationOUtside/nb_js_diagrammers.git`
or:
`pip install --upgrade https://github.com/innovationOUtside/nb_js_diagrammers/archive/main.zip`
## Usage
Load the magics into a notebook using:
`%load_ext nb_js_diagrammers`
All magics support a `-o / --outfile` that can be used to specify the name of a generated html file that is then embedded in the notebook via an iframe. If no filename is specified, a filename with a randomly generated UID based will be created.
You can then generate diagrams using the appropriate diagram syntax and block magic.
The `flowchart_magic`, `mermaid_magic` and `wavedrom_magic` also act as line magics. Put the diagram script into a variable (`my_script`) then call as `%mermaid_magic --src my_script -h 1000` etc.
__Note that for block magics, the code cell MUST start the `%%` - even blank lines and comment lines preceding the the block magic will raise an error.__
```text
%%flowchart_magic -h 100 -o flowchart.html
st=>start: Start
e=>end: End
op1=>operation: Generate
op2=>parallel: Evaluate
st(right)->op1(right)->op2
op2(path1, top)->op1
op2(path2, right)->e
```
```text
%%wavedrom_magic -h 100
{ signal : [
{ name: "clk", wave: "p......" },
{ name: "bus", wave: "x.34.5x", data: "head body tail" },
{ name: "wire", wave: "0.1..0." },
]}
```
```text
%%mermaid_magic -h 500
flowchart TD
A[Start] --> B{Is it?};
B -->|Yes| C[OK];
C --> D[Rethink];
D --> B;
B ---->|No| E[End];
```
```text
%%mermaid_magic -h 250
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
```text
%%mermaid_magic -h 350
sequenceDiagram
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
```
```text
%%mermaid_magic -h 330
erDiagram
CUSTOMER ||--o{ ORDER : places
CUSTOMER {
string name
string custNumber
string sector
}
ORDER {
int orderNumber
string deliveryAddress
}
```
```text
%wavesurfer_magic -f https://ia802606.us.archive.org/35/items/shortpoetry_047_librivox/abou_ben_adhem_hunt_mlb.mp3
```
## Generating Flowcharts from Python Code
An additional magic is provided that uses the [`pyflowchart`](https://github.com/cdfmlr/pyflowchart/) package to generate a flowchart describing Python code cell in an appropriately magicked code cell:
```text
%%pyflowchart_magic -h 800
import time
def demo(msg='demo'):
for i in range(10):
print(f'{msg} loopcount is {i}')
time.sleep(i)
```
The `-x / --execute` flag will execute the code in the current notebook scope. *Without the flag, the code is not executed.*
More clunkily, we can also grab and chart code from an executed code cell using the following recipe (this captures cell content from the previously executed cell):
```python
%%capture code
# This gets the content of the previous cell
# and stores it in the variable: code
%history -l 1
```
We can then render a flowchart from the captured code cell content:
```python
from pyflowchart import Flowchart
from nb_js_diagrammers.flowchartjs import TEMPLATE_FLOWCHARTJS
from nb_js_diagrammers.magics import js_ui
# Generate a flowchart from the grabbed code
fc = Flowchart.from_code(code.stdout)
# Render the flowchart via an external, IFrame embedded HTML page - DEPRECATED
# (Code in package but commented out)
#js_ui({"src":fc.flowchart()}, TEMPLATE_FLOWCHARTJS, height=800)
# Render flowchart via repr_html IFrame with html in srcdoc
diagram = JSDiagram(fc.flowchart()}, TEMPLATE_FLOWCHARTJS, height=200)
diagram
```
We can also save the HTML to a file:
```python
diagram.save_html("myfile.html")
```
## Generating Static Image Files
To generate static image files using `mermaid.js`, see: https://github.com/mermaid-js/mermaid-cli
The `wavedrom` images have a save as png or SVG option (right click over diagram)
## Further reading
[*A Simple Pattern for Embedding Third Party Javascript Generated Graphics in Jupyter Notebooks*](https://blog.ouseful.info/2021/09/30/a-simple-pattern-for-embedding-third-party-javascript-generated-graphics-in-jupyter-notebools/)
## See also
[*Previewing Sphinx and Jupyter Book Rendered Mermaid and Wavedrom Diagrams in VS Code*](https://blog.ouseful.info/2021/11/02/previewing-sphinx-and-jupyter-book-rendered-mermaid-and-wavedrom-diagrams-in-vs-code/)
Raw data
{
"_id": null,
"home_page": "https://github.com/innovationOUtside/nb_js_diagrammers",
"name": "nb-js-diagrammers",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Tony Hirst",
"author_email": "tony.hirst@open.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/25/b9/328f96caf2d8440975305b72b138d02e33d05bcc1dbab18f5cb9d48b6e52/nb-js-diagrammers-0.0.9.tar.gz",
"platform": null,
"description": "# nb_js_diagrammers\n\nIPython magics for rendering diagrams from simple scripts in Jupyter notebooks using various JavaScript diagram generators.\n\nSimple magics for rendering diagrams from line and cell magics using the following JavaScript diagram generators:\n\n- [Mermaid.js](https://mermaid-js.github.io/mermaid/#/): a wide variety of diagram types, including flowcharts, sequence diagrams, entity relationship diagrams\n- [flowchart.js](http://flowchart.js.org/): flowchart generator\n- [wavedrom](https://github.com/wavedrom/wavedrom): timing diagram generator\n- [waversurfer.js](https://wavesurfer-js.org/): audio waveform visualisation\n\n## Installation\n\nInstall from PyPi as: `pip install --upgrade nb-js-diagrammers`\n\nInstall direct from this repository as:\n\n`pip install --upgrade git+https://github.com/innovationOUtside/nb_js_diagrammers.git`\n\nor:\n\n`pip install --upgrade https://github.com/innovationOUtside/nb_js_diagrammers/archive/main.zip`\n\n## Usage\n\nLoad the magics into a notebook using:\n\n`%load_ext nb_js_diagrammers`\n\nAll magics support a `-o / --outfile` that can be used to specify the name of a generated html file that is then embedded in the notebook via an iframe. If no filename is specified, a filename with a randomly generated UID based will be created.\n \nYou can then generate diagrams using the appropriate diagram syntax and block magic.\n\nThe `flowchart_magic`, `mermaid_magic` and `wavedrom_magic` also act as line magics. Put the diagram script into a variable (`my_script`) then call as `%mermaid_magic --src my_script -h 1000` etc.\n\n__Note that for block magics, the code cell MUST start the `%%` - even blank lines and comment lines preceding the the block magic will raise an error.__\n\n```text\n%%flowchart_magic -h 100 -o flowchart.html\n\nst=>start: Start\ne=>end: End\nop1=>operation: Generate\nop2=>parallel: Evaluate\nst(right)->op1(right)->op2\nop2(path1, top)->op1\nop2(path2, right)->e\n```\n\n\n\n```text\n%%wavedrom_magic -h 100\n\n{ signal : [\n { name: \"clk\", wave: \"p......\" },\n { name: \"bus\", wave: \"x.34.5x\", data: \"head body tail\" },\n { name: \"wire\", wave: \"0.1..0.\" },\n]}\n```\n\n\n\n```text\n%%mermaid_magic -h 500\n\nflowchart TD\n A[Start] --> B{Is it?};\n B -->|Yes| C[OK];\n C --> D[Rethink];\n D --> B;\n B ---->|No| E[End];\n```\n\n\n\n```text\n%%mermaid_magic -h 250\n\ngraph TD;\n A-->B;\n A-->C;\n B-->D;\n C-->D;\n```\n\n\n\n```text\n%%mermaid_magic -h 350\n\nsequenceDiagram\n Alice->>John: Hello John, how are you?\n John-->>Alice: Great!\n Alice-)John: See you later!\n```\n\n\n\n```text\n%%mermaid_magic -h 330\n\nerDiagram\n CUSTOMER ||--o{ ORDER : places\n CUSTOMER {\n string name\n string custNumber\n string sector\n }\n ORDER {\n int orderNumber\n string deliveryAddress\n }\n```\n\n\n\n```text\n%wavesurfer_magic -f https://ia802606.us.archive.org/35/items/shortpoetry_047_librivox/abou_ben_adhem_hunt_mlb.mp3\n```\n\n\n\n## Generating Flowcharts from Python Code\n\nAn additional magic is provided that uses the [`pyflowchart`](https://github.com/cdfmlr/pyflowchart/) package to generate a flowchart describing Python code cell in an appropriately magicked code cell:\n\n```text\n%%pyflowchart_magic -h 800\nimport time\n\ndef demo(msg='demo'):\n for i in range(10):\n print(f'{msg} loopcount is {i}')\n time.sleep(i)\n```\n\nThe `-x / --execute` flag will execute the code in the current notebook scope. *Without the flag, the code is not executed.*\n\nMore clunkily, we can also grab and chart code from an executed code cell using the following recipe (this captures cell content from the previously executed cell):\n\n```python\n%%capture code\n# This gets the content of the previous cell\n# and stores it in the variable: code\n%history -l 1\n```\n\nWe can then render a flowchart from the captured code cell content:\n\n```python\nfrom pyflowchart import Flowchart\n\nfrom nb_js_diagrammers.flowchartjs import TEMPLATE_FLOWCHARTJS\nfrom nb_js_diagrammers.magics import js_ui\n\n# Generate a flowchart from the grabbed code\nfc = Flowchart.from_code(code.stdout)\n\n# Render the flowchart via an external, IFrame embedded HTML page - DEPRECATED\n# (Code in package but commented out)\n#js_ui({\"src\":fc.flowchart()}, TEMPLATE_FLOWCHARTJS, height=800)\n\n# Render flowchart via repr_html IFrame with html in srcdoc\ndiagram = JSDiagram(fc.flowchart()}, TEMPLATE_FLOWCHARTJS, height=200)\ndiagram\n```\n\nWe can also save the HTML to a file:\n\n```python\ndiagram.save_html(\"myfile.html\")\n```\n\n## Generating Static Image Files\n\nTo generate static image files using `mermaid.js`, see: https://github.com/mermaid-js/mermaid-cli\n\nThe `wavedrom` images have a save as png or SVG option (right click over diagram)\n\n## Further reading\n\n[*A Simple Pattern for Embedding Third Party Javascript Generated Graphics in Jupyter Notebooks*](https://blog.ouseful.info/2021/09/30/a-simple-pattern-for-embedding-third-party-javascript-generated-graphics-in-jupyter-notebools/)\n\n## See also\n\n[*Previewing Sphinx and Jupyter Book Rendered Mermaid and Wavedrom Diagrams in VS Code*](https://blog.ouseful.info/2021/11/02/previewing-sphinx-and-jupyter-book-rendered-mermaid-and-wavedrom-diagrams-in-vs-code/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Javascript diagrammers and magics for IPython and Jupyter notebooks",
"version": "0.0.9",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b99a4102d3e36f20138abbf54b804adf03c5833dac6112acba5f79bf0fb178b6",
"md5": "9153f21f59d3286c4ac228ce90eb867a",
"sha256": "db2a60adfaf85851afc4cd8ec34b61dbab7137bd669b32066013c999fb8243fa"
},
"downloads": -1,
"filename": "nb_js_diagrammers-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9153f21f59d3286c4ac228ce90eb867a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8958,
"upload_time": "2023-04-05T16:30:09",
"upload_time_iso_8601": "2023-04-05T16:30:09.360466Z",
"url": "https://files.pythonhosted.org/packages/b9/9a/4102d3e36f20138abbf54b804adf03c5833dac6112acba5f79bf0fb178b6/nb_js_diagrammers-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "25b9328f96caf2d8440975305b72b138d02e33d05bcc1dbab18f5cb9d48b6e52",
"md5": "70160ed4a0c1136287afa00212b85d29",
"sha256": "9a6345e920ee5f1750582ac296411288fa1995d53658b9f4945941522c170521"
},
"downloads": -1,
"filename": "nb-js-diagrammers-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "70160ed4a0c1136287afa00212b85d29",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9779,
"upload_time": "2023-04-05T16:30:11",
"upload_time_iso_8601": "2023-04-05T16:30:11.386299Z",
"url": "https://files.pythonhosted.org/packages/25/b9/328f96caf2d8440975305b72b138d02e33d05bcc1dbab18f5cb9d48b6e52/nb-js-diagrammers-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-05 16:30:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "innovationOUtside",
"github_project": "nb_js_diagrammers",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "nb-js-diagrammers"
}
JSON
