{
"info": {
"author": "Geoffrey M. Poore",
"author_email": "gpoore@gmail.com",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 4 - Beta",
"Environment :: Console",
"Intended Audience :: Developers",
"Intended Audience :: Education",
"Intended Audience :: Science/Research",
"License :: OSI Approved :: BSD License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3.5",
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.7",
"Topic :: Documentation",
"Topic :: Education",
"Topic :: Software Development",
"Topic :: Software Development :: Build Tools",
"Topic :: Software Development :: Documentation",
"Topic :: Text Processing",
"Topic :: Text Processing :: Markup"
],
"description": "# Codebraid \u2013 live code in Pandoc Markdown\n\nCodebraid is a Python program that enables executable code in\n[Pandoc](http://pandoc.org/) Markdown documents. Using Codebraid can be as\nsimple as adding a class to your code blocks' attributes, and then running\n`codebraid` rather than `pandoc` to convert your document from Markdown to\nanother format. `codebraid` supports almost all of `pandoc`'s options and\npasses them to `pandoc` internally.\n\nCodebraid provides two options for executing code. It includes a built-in\ncode execution system that currently supports **Python 3.5+**, **Julia**,\n**Rust**, **R**, **Bash**, and **JavaScript**. Code can also be executed\nusing **Jupyter kernels**, with support for rich output like plots.\n\n**Development:** https://github.com/gpoore/codebraid\n\nView example HTML output, or see the Markdown source or raw HTML (the Python\nand Rust examples demonstrate more advanced features at the end):\n\n * [Python example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/python.html)\n [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/python.cbmd)]\n [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/python.html)]\n * [Jupyter example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/jupyter.html)\n [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/jupyter.cbmd)]\n [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/jupyter.html)]\n * [Rust example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/rust.html)\n [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/rust.cbmd)]\n [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/rust.html)]\n * [Julia example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/julia.html)\n [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/julia.cbmd)]\n [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/julia.html)]\n * [R example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/R.html)\n [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/R.cbmd)]\n [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/R.html)]\n * [Bash example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/bash.html)\n [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/bash.cbmd)]\n [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/bash.html)]\n * [JavaScript example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/javascript.html)\n [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/javascript.cbmd)]\n [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/javascript.html)]\n\n\n## Simple example\n\nMarkdown source `test.md`:\n\n``````markdown\n```{.python .cb.run}\nvar = 'Hello from Python!'\nvar += ' $2^8 = {}$'.format(2**8)\n```\n\n```{.python .cb.run}\nprint(var)\n```\n``````\n\nRun `codebraid` (to save the output, add something like `-o test_out.md`, and\nadd `--overwrite` if it already exists):\n\n```shell\ncodebraid pandoc --from markdown --to markdown test.md\n```\n\nOutput:\n\n```markdown\nHello from Python! $2^8 = 256$\n```\n\nAs this example illustrates, variables persist between code blocks; by\ndefault, code is executed within a single session. Code output is also cached\nby default so that code is only re-executed when modified.\n\n\n## Features\n\n### Comparison with [Jupyter](https://jupyter.org/), [knitr](https://yihui.name/knitr/), and [Pweave](http://mpastell.com/pweave/)\n\n| | Codebraid | Jupyter Notebook | knitr | Pweave |\n|------------------------------------------------|-----------|------------------|----------|----------|\n| multiple programming languages per document | ✓ | ✓* | ✓\u2020 | ✓* |\n| multiple independent sessions per language | ✓ | | | |\n| inline code execution within paragraphs | ✓ | | ✓ | ✓ |\n| no out-of-order code execution | ✓ | | ✓\u2021 | ✓ |\n| no markdown preprocessor or custom syntax | ✓ | ✓ | | |\n| minimal diffs for easy version control | ✓ | | ✓ | ✓ |\n| insert code output anywhere in a document | ✓ | | ✓ | |\n| can divide code into incomplete snippets | ✓ | | ✓ | ✓ |\n| support for literate programming | ✓ | | ✓ | |\n| compatible with any text editor | ✓ | | ✓ | ✓ |\n\n* One primary language from the Jupyter kernel. The IPython kernel\nsupports additional languages via `%%script` magics. There is no continuity\nbetween `%%script` cells, because each cell is executed in a separate process.\nSome magics, such as those provided by\n[PyJulia](https://pyjulia.readthedocs.io) and\n[rpy2](https://rpy2.readthedocs.io), provide more advanced capabilities.\n
\n\u2020 knitr only provides continuity between code chunks for R, and more recently\nPython and Julia. Code chunks in other languages are executed individually\nin separate processes.\n
\n\u2021 Out-of-order execution is possible with R Markdown notebooks.\n\n