rootmd


Namerootmd JSON
Version 0.6.1 PyPI version JSON
download
home_pagehttps://github.com/jdbrice/RootMD
SummaryRootMD 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_time2023-05-19 12:37:42
maintainer
docs_urlNone
authorDaniel 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

```

![h1.svg](h1.svg)

## 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![h1.svg](h1.svg)\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"
}
        
Elapsed time: 0.17690s