| Name | rootmd JSON |
| Version |
0.6.1
JSON |
| download |
| home_page | https://github.com/jdbrice/RootMD |
| Summary | RootMD is a markdown processor for markdown with ROOT-flavored c++ code. RootMD can execute c++ code and inject the output (from stdout, stderr) and link or embed image outputs |
| upload_time | 2023-05-19 12:37:42 |
| maintainer | |
| docs_url | None |
| author | Daniel Brandenburg |
| requires_python | >=3.8,<4.0 |
| license | |
| keywords |
root
markdown
physics
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# RootMD 🩺 👩🏼⚕️
Scientific reports/literate programming tool for CERN ROOT and c++. RootMD is a markdown (and other format) processor for mark up with ROOT-flavored c++ code. RootMD can execute c++ code and inject the output (from stdout, stderr) and link or embed image outputs. Provides a format for producing code + result for better documentation / notes. This is by design not a jupyter notebook, e.g. not a REPL-like environment. If you like Jupyter notebooks then use that :).
## Installation
```sh
python -m pip install rootmd
```
the you can use it with:
```
python -m rootmd <args>
```
## Features
- execute c++ code blocks via ROOT REPL
- capture stdout, stderr and inject into output
- embed (base64) or link to any image files produced
- output to HTML, Markdown (or obsidian flavored markdown), or as a presentation (via Marp)
- execute html, css, javascript code blocks (for html output) to customize output
- watch files for changes and rerun (good for iterative workflows)
## usage
```sh
usage: rootmd [-h] [--output OUTPUT]
[--format {html,md,obsidian,json,terminal}] [--embed]
[--asset-dir ASSET_DIR] [--verbosity VERBOSITY]
[--watch WATCH] [--run RUN] [--clean] [--no-exec]
input
Convert Markdown with inline c++ code to ROOT output.
positional arguments:
input input Markdown file to execute and convert
optional arguments:
-h, --help show this help message and exit
--output OUTPUT output filename default <input>.<ext> where <ext>
is determined by the chosen format, default html
--format {html,md,obsidian,json,terminal}
output format
--embed embed images as base 64
--asset-dir ASSET_DIR
specify asset output directory, paths are NOTE re-
written to support unless using obsidian format
--verbosity VERBOSITY
specify log verbosity
--watch WATCH watch a file or directory for changes
--run RUN command to run after processing a file. The
filename can be substituted into the command string
with {{file}}. Example: --run="echo {{file}}"
--clean clean artifacts, caution - should only use with
embed or asset copy to <asset-dir>
--no-exec Do not execute any code blocks, just process file
(useful for viewing and testing conversion)
```
## TODO
- [x] make it a python package (so that it can be installed via pip)
- [x] Look into poetry
- [x] start versioning
- [x] support output verbosity levels
- & make output useful
- Add comment for input block identification upon processing
- [x] add watch functionality for reprocessing a file on change
- [ ] Add some additional features
- [ ] Handle watch of multiple files, and how output filename should be named
- [x] Add terminal output using rich pretty output package
- consider iterm image support? [See here](https://iterm2.com/documentation-images.html)
- [x] Basically, markdown output on the terminal : using rich
- [x] Add prismjs for inline code
- test some failure modes when root code has errors leading to hang
- [x] add mathjax to html output for inline mathematics
- [x] "import" source files into output? So that you can write code in separate file but sow it in the output?
- add as a block option
- support for other "languages", e.g. shell
- support for ROOTJS in HTML output
- embed histogram as JSON object in HTML
- [x] clean assets in embed mode or other output path
- download + embed external JS for fully contained, offline ready single file HTML output
- [x] Load HTML / CSS defaults from a file in the package
- [x] Better style HTML output (input / output cells more like Jupyter)
- Consider adding JS for collapsing headings, output blocks etc.
- [ ] add format option to output a ROOT macro with markdown and output converted to comments
- [x] integrate usage of RNUplot for graphical output!
- [x] implement an auto-draw so that you dont have to "Print(...)" every block
- [ ] block option: run code block as a "macro"
- [x] You can already use .L, .x
- [ ] move ROOT executor into member not superclass
- [ ] auto-draw dont do it for cells without any drawing!
- [x] PDF support
- [ ] Better PDF embed (link to file) (for Firefox especially) using canvas : https://stackoverflow.com/questions/2104608/hiding-the-toolbars-surrounding-an-embedded-pdf
- [ ] Embed PDF base64 in object tag
## Feature wish list
- Cache blocks of code for faster rerun
- server for "sharing" of documents, from command line - use secret links
- Technique for RAW output?
- i.e. write out HTML Table or markup
- inline code replacement, e.g. "We ran `TString::Format("%d",tree->GetEntries())` events."
## Improve ROOT?
- Apply some default style options
-
## Known issues
- watch isnt working, especially when input not given
- something is surely broken
### ROOT REPL issues
ROOT REPL struggles with multi-line code:
- function definitions with "{" on next line does not work since it doesn't understand
```cpp
void hello() {
// this works
}
void world()
{
// this DOES NOT work
}
```
## Code Block Options
- `stdout` or `out`: Default `true`. Set to `false` to hide stdout block. Set to <filename> to write output to the given file.
- `stderr` or `err`: Default `true`. Set to `false` to hide stderr block. Set to <filename> to write output to the given file.
- `silent` or `quiet`: Default `false`. Set to `true` to hide both stderr and stdout
- HTML only
- `.image`: css class to use for produced images.
- `raw`: output raw result from `stdout` as html
## Dependencies
RootMD itself is a pure python package which uses:
- [mistletoe](https://github.com/miyuchina/mistletoe) : python markdown parser and processor
- [rich](https://github.com/Textualize/rich) : Rich for pretty terminal output
- pyyaml : for parsing yaml front matter
- Dependencies for HTML output
- [prismjs](https://prismjs.com/) for syntax highlighting in HTML output
- [mathjax](https://www.mathjax.org/) for rendering mathematics
- [ROOT](https://root.cern.ch/) : installed on system and available on PATH
## Example : see [example_in.md](example_in.md) and [example.md](example.md)
This is a simple example of markdown processed by RootMD.
You can include any c++ code that ROOT can handle. For instance (using ROOT6)
this part of the file was processed with
```sh
rootmd example_in.md -f md -o example.md
```
```cpp
cout << "Hello from ROOT (stdout)" << endl;
cerr << "Hello from ROOT (stderr)" << endl;
```
```sh
# Block [0]
Hello from ROOT (stdout)
Hello from ROOT (stderr)
```
```cpp
TH1 * h1 = new TH1F( "hGaus", ";x;counts", 100, -5, 5 );
h1->FillRandom( "gaus", 10000 );
h1->Draw( "pe" );
h1->Draw( "same hist" );
gPad->Print( "h1.svg" );
```
```sh
# Block [1]
Info in <TCanvas::MakeDefCanvas>: created default TCanvas with name c1
Info in <TCanvas::Print>: SVG file h1.svg has been created
```
## Changelog
### v0.6
- Fix broken options in MdRender
### v0.6
- Add control of output blocks to MdRenderer, update README
### v0.5.9
- Add additional executor catch
- Catch "_sigtramp"
- Catch "(no debug info)"
### v0.5.8
- Allow log level to be set from command line arguments.
- Adds parameter "--log" or "--logLevel
### v0.5.7
- Add additional catch conditions on the ROOT executor to try to prevent hanging on code errors
- Catch "Root >"
- Catch "root [N]"
- Catch "*** Break *** segmentation violation"
Raw data
{
"_id": null,
"home_page": "https://github.com/jdbrice/RootMD",
"name": "rootmd",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "root,markdown,physics",
"author": "Daniel Brandenburg",
"author_email": "hello@jdbburg.com",
"download_url": "https://files.pythonhosted.org/packages/03/d4/6f9d27889c731359f4ee90c3bcefc42c4562bd538d3dc3967460a8ec241a/rootmd-0.6.1.tar.gz",
"platform": null,
"description": "\n# RootMD \ud83e\ude7a \ud83d\udc69\ud83c\udffc\u200d\u2695\ufe0f\n\nScientific reports/literate programming tool for CERN ROOT and c++. RootMD is a markdown (and other format) processor for mark up with ROOT-flavored c++ code. RootMD can execute c++ code and inject the output (from stdout, stderr) and link or embed image outputs. Provides a format for producing code + result for better documentation / notes. This is by design not a jupyter notebook, e.g. not a REPL-like environment. If you like Jupyter notebooks then use that :). \n\n## Installation\n\n```sh\npython -m pip install rootmd\n```\n\nthe you can use it with:\n```\npython -m rootmd <args>\n```\n\n## Features\n- execute c++ code blocks via ROOT REPL\n- capture stdout, stderr and inject into output\n- embed (base64) or link to any image files produced \n- output to HTML, Markdown (or obsidian flavored markdown), or as a presentation (via Marp)\n- execute html, css, javascript code blocks (for html output) to customize output\n- watch files for changes and rerun (good for iterative workflows)\n\n## usage\n```sh\nusage: rootmd [-h] [--output OUTPUT]\n [--format {html,md,obsidian,json,terminal}] [--embed]\n [--asset-dir ASSET_DIR] [--verbosity VERBOSITY]\n [--watch WATCH] [--run RUN] [--clean] [--no-exec]\n input\n\nConvert Markdown with inline c++ code to ROOT output.\n\npositional arguments:\n input input Markdown file to execute and convert\n\noptional arguments:\n -h, --help show this help message and exit\n --output OUTPUT output filename default <input>.<ext> where <ext>\n is determined by the chosen format, default html\n --format {html,md,obsidian,json,terminal}\n output format\n --embed embed images as base 64\n --asset-dir ASSET_DIR\n specify asset output directory, paths are NOTE re-\n written to support unless using obsidian format\n --verbosity VERBOSITY\n specify log verbosity\n --watch WATCH watch a file or directory for changes\n --run RUN command to run after processing a file. The\n filename can be substituted into the command string\n with {{file}}. Example: --run=\"echo {{file}}\"\n --clean clean artifacts, caution - should only use with\n embed or asset copy to <asset-dir>\n --no-exec Do not execute any code blocks, just process file\n (useful for viewing and testing conversion)\n\n```\n\n\n## TODO\n- [x] make it a python package (so that it can be installed via pip)\n - [x] Look into poetry\n - [x] start versioning\n- [x] support output verbosity levels \n - & make output useful\n- Add comment for input block identification upon processing\n- [x] add watch functionality for reprocessing a file on change\n - [ ] Add some additional features\n - [ ] Handle watch of multiple files, and how output filename should be named\n- [x] Add terminal output using rich pretty output package\n - consider iterm image support? [See here](https://iterm2.com/documentation-images.html)\n - [x] Basically, markdown output on the terminal : using rich\n- [x] Add prismjs for inline code\n- test some failure modes when root code has errors leading to hang\n- [x] add mathjax to html output for inline mathematics\n- [x] \"import\" source files into output? So that you can write code in separate file but sow it in the output?\n - add as a block option\n- support for other \"languages\", e.g. shell\n- support for ROOTJS in HTML output\n - embed histogram as JSON object in HTML\n- [x] clean assets in embed mode or other output path\n- download + embed external JS for fully contained, offline ready single file HTML output\n- [x] Load HTML / CSS defaults from a file in the package\n- [x] Better style HTML output (input / output cells more like Jupyter)\n - Consider adding JS for collapsing headings, output blocks etc.\n- [ ] add format option to output a ROOT macro with markdown and output converted to comments\n- [x] integrate usage of RNUplot for graphical output!\n- [x] implement an auto-draw so that you dont have to \"Print(...)\" every block\n- [ ] block option: run code block as a \"macro\" \n - [x] You can already use .L, .x\n- [ ] move ROOT executor into member not superclass\n- [ ] auto-draw dont do it for cells without any drawing!\n- [x] PDF support\n- [ ] Better PDF embed (link to file) (for Firefox especially) using canvas : https://stackoverflow.com/questions/2104608/hiding-the-toolbars-surrounding-an-embedded-pdf\n- [ ] Embed PDF base64 in object tag\n## Feature wish list\n- Cache blocks of code for faster rerun\n- server for \"sharing\" of documents, from command line - use secret links\n- Technique for RAW output? \n - i.e. write out HTML Table or markup\n- inline code replacement, e.g. \"We ran `TString::Format(\"%d\",tree->GetEntries())` events.\"\n\n## Improve ROOT?\n- Apply some default style options\n- \n\n## Known issues\n- watch isnt working, especially when input not given\n- something is surely broken\n### ROOT REPL issues\nROOT REPL struggles with multi-line code:\n- function definitions with \"{\" on next line does not work since it doesn't understand\n```cpp\nvoid hello() {\n // this works\n}\n\nvoid world() \n{\n // this DOES NOT work\n}\n```\n## Code Block Options\n- `stdout` or `out`: Default `true`. Set to `false` to hide stdout block. Set to <filename> to write output to the given file.\n- `stderr` or `err`: Default `true`. Set to `false` to hide stderr block. Set to <filename> to write output to the given file.\n- `silent` or `quiet`: Default `false`. Set to `true` to hide both stderr and stdout\n- HTML only\n - `.image`: css class to use for produced images.\n - `raw`: output raw result from `stdout` as html\n\n## Dependencies\nRootMD itself is a pure python package which uses:\n- [mistletoe](https://github.com/miyuchina/mistletoe) : python markdown parser and processor\n- [rich](https://github.com/Textualize/rich) : Rich for pretty terminal output\n- pyyaml : for parsing yaml front matter\n- Dependencies for HTML output\n - [prismjs](https://prismjs.com/) for syntax highlighting in HTML output\n - [mathjax](https://www.mathjax.org/) for rendering mathematics\n- [ROOT](https://root.cern.ch/) : installed on system and available on PATH\n\n\n\n## Example : see [example_in.md](example_in.md) and [example.md](example.md)\nThis is a simple example of markdown processed by RootMD.\nYou can include any c++ code that ROOT can handle. For instance (using ROOT6)\nthis part of the file was processed with\n```sh\nrootmd example_in.md -f md -o example.md\n\n```\n\n```cpp\ncout << \"Hello from ROOT (stdout)\" << endl;\ncerr << \"Hello from ROOT (stderr)\" << endl;\n\n```\n```sh\n# Block [0]\nHello from ROOT (stdout)\nHello from ROOT (stderr)\n\n```\n\n```cpp\nTH1 * h1 = new TH1F( \"hGaus\", \";x;counts\", 100, -5, 5 );\nh1->FillRandom( \"gaus\", 10000 );\nh1->Draw( \"pe\" );\nh1->Draw( \"same hist\" );\ngPad->Print( \"h1.svg\" );\n\n```\n```sh\n# Block [1]\nInfo in <TCanvas::MakeDefCanvas>: created default TCanvas with name c1\nInfo in <TCanvas::Print>: SVG file h1.svg has been created\n\n```\n\n\n\n## Changelog\n\n### v0.6\n- Fix broken options in MdRender\n### v0.6\n- Add control of output blocks to MdRenderer, update README\n### v0.5.9\n- Add additional executor catch\n - Catch \"_sigtramp\" \n - Catch \"(no debug info)\"\n\n### v0.5.8\n- Allow log level to be set from command line arguments. \n - Adds parameter \"--log\" or \"--logLevel\n\n### v0.5.7\n- Add additional catch conditions on the ROOT executor to try to prevent hanging on code errors\n - Catch \"Root >\" \n - Catch \"root [N]\"\n - Catch \"*** Break *** segmentation violation\"",
"bugtrack_url": null,
"license": "",
"summary": "RootMD is a markdown processor for markdown with ROOT-flavored c++ code. RootMD can execute c++ code and inject the output (from stdout, stderr) and link or embed image outputs",
"version": "0.6.1",
"project_urls": {
"Homepage": "https://github.com/jdbrice/RootMD",
"Repository": "https://github.com/jdbrice/RootMD"
},
"split_keywords": [
"root",
"markdown",
"physics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6c34d3776771bf846fef885ed5122b771de175383b0d91e1132342247d34e0af",
"md5": "d5136003e6750c029b685c77fc7a2b73",
"sha256": "fb91eb0acab35d7481eaa184b092b2d587e168fea3b9686afc11052c20ba14fa"
},
"downloads": -1,
"filename": "rootmd-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5136003e6750c029b685c77fc7a2b73",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 98443,
"upload_time": "2023-05-19T12:37:40",
"upload_time_iso_8601": "2023-05-19T12:37:40.063090Z",
"url": "https://files.pythonhosted.org/packages/6c/34/d3776771bf846fef885ed5122b771de175383b0d91e1132342247d34e0af/rootmd-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "03d46f9d27889c731359f4ee90c3bcefc42c4562bd538d3dc3967460a8ec241a",
"md5": "4b58b8ebf7d5ae2f9659a6300edf7db0",
"sha256": "bf0baf88327a598dafc60279fc5d5375abadf5cfc86072bd8fcf7b74a523b593"
},
"downloads": -1,
"filename": "rootmd-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "4b58b8ebf7d5ae2f9659a6300edf7db0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 57062,
"upload_time": "2023-05-19T12:37:42",
"upload_time_iso_8601": "2023-05-19T12:37:42.023788Z",
"url": "https://files.pythonhosted.org/packages/03/d4/6f9d27889c731359f4ee90c3bcefc42c4562bd538d3dc3967460a8ec241a/rootmd-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-19 12:37:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jdbrice",
"github_project": "RootMD",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "rootmd"
}
