Metadata-Version: 2.1
Name: codebraid
Version: 0.2.0
Summary: Live code in Pandoc Markdown
Home-page: http://github.com/gpoore/codebraid
Author: Geoffrey M. Poore
Author-email: gpoore@gmail.com
License: BSD
Keywords: dynamic documents,reproducible research,notebook,markdown,pandoc,LaTeX
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Documentation
Classifier: Topic :: Education
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.5
Description-Content-Type: text/markdown
Requires-Dist: bespon (>=0.3)

# Codebraid – live code in Pandoc Markdown

Codebraid is a Python program that enables executable code in
[Pandoc](http://pandoc.org/) Markdown documents.  Using Codebraid can be as
simple as adding a class to your code blocks' attributes, and then running
`codebraid` rather than `pandoc` to convert your document from Markdown to
another format.  `codebraid` supports almost all of `pandoc`'s options and
passes them to `pandoc` internally.

Codebraid currently can run **Python 3.5+**, **Julia**, **Rust**, and **R**
code.  Support for additional languages is coming soon.

**Development:**  https://github.com/gpoore/codebraid

View example HTML output, or see the Markdown source or raw HTML (the Rust
example demonstrates more advanced features):

  * [Python example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/python.html)
    [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/python.cbmd)]
    [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/python.html)]
  * [Julia example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/julia.html)
    [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/julia.cbmd)]
    [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/julia.html)]
  * [Rust example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/rust.html)
    [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/rust.cbmd)]
    [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/rust.html)]
  * [R example](https://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/R.html)
    [[Pandoc Markdown source](https://github.com/gpoore/codebraid/blob/master/examples/R.cbmd)]
    [[raw HTML](https://github.com/gpoore/codebraid/blob/master/examples/R.html)]


## Simple example

Markdown source `test.md`:

``````markdown
```{.python .cb.run}
print('Hello from Python!')
print('$2^8 = {}$'.format(2**8))
```
``````

Run `codebraid` (to save the output, add something like `-o test_out.md`, and
add `--overwrite` if it already exists):

```shell
codebraid pandoc --from markdown --to markdown test.md
```

Output:

```markdown
Hello from Python! $2^8 = 256$
```


## Features

**Easy debugging** — By default, stderr is shown automatically in the document
whenever there is an error, right next to the code that caused it.  Even
though user code is typically inserted into a template for execution, line
numbers in error messages will correctly correspond with line numbers in code
blocks, because Codebraid tracks the origin of each line of code and
synchronizes error messages.

**Simple language support** — Adding support for a new language can take only
a few minutes.  Codebraid's default system for executing code is based on
writing delimiters to stdout and stderr that allow it to associate code output
with individual code chunks.  Adding a language is as simple as creating a
config file that tells Codebraid which program to run, which file extension to
use, and how to write to stdout and stderr.  See
[`languages/`](https://github.com/gpoore/codebraid/tree/master/codebraid/languages)
for examples.

**No preprocessor** — Unlike many approaches to making code in Markdown
executable, Codebraid is not a preprocessor.  Rather, Codebraid acts on the
abstract syntax tree (AST) that Pandoc generates when parsing a document.
Preprocessors often fail to disable commented-out code blocks because the
preprocessor doesn't recognize Markdown comments.  Preprocessors can also fail
due to the finer points of Markdown parsing.  None of this is an issue for
Codebraid, because Pandoc does the Markdown parsing.

**No custom syntax** — Codebraid introduces no additional Markdown syntax.
Making a code block or inline code executable uses Pandoc's existing syntax
for defining code attributes.



## Installation and requirements

**Installation:**  `pip3 install codebraid` or `pip install codebraid`

Manual installation:  `python3 setup.py install` or `python setup.py install`

**Requirements:**

  * [Pandoc](http://pandoc.org/) 2.4+
  * Python 3.5+ with `setuptools`, and [`bespon`](https://bespon.org) 0.3
    (`bespon` installation is typically managed by `pip`/`setup.py`)

By default, the `python3` executable will be used to execute code.  If it does
not exist, `python` will be tried to account for Windows and Arch Linux.
Future releases will allow specifying the executable on systems with multiple
Python 3 installations.


## Converting a document

Simply run `codebraid pandoc <normal pandoc options>`.  Note that
`--overwrite` is required for existing files.

`codebraid` should typically be run in the same directory as the document, so
that the default working directory for code is the document directory.  Future
releases will allow customization of the working directory.


## Caching

By default, code output is cached, and code is only re-executed when it is
modified.  The default cache location is a `_codebraid` directory in the
directory with your markdown document.  This can be modified using
`--cache-dir`.  Sharing a single cache location between multiple documents is
not yet supported.

If you are working with external data that changes, you should run `codebraid`
with `--no-cache` to prevent the cache from becoming out of sync with your
data.  Future releases will allow external dependencies to be specified so
that caching will work correctly in these situations.


## Code options

### Classes

Code is made executable by adding a Codebraid class to its
[Pandoc attributes](http://pandoc.org/MANUAL.html#fenced-code-blocks).
For example, `` `code`{.python}` `` becomes
`` `code`{.python .cb.run}` ``.

* `.cb.expr` — Evaluate an expression and interpret the result as Markdown.
  Only works with inline code.

* `.cb.run` — Run code and interpret any printed content (stdout) as Markdown.
  Also insert stderr verbatim (as code) if it exists.

* `.cb.nb` — Notebook mode.  For inline code, this is equivalent to
  `.cb.expr`.  For code blocks, this inserts the code verbatim, followed by
  the stdout verbatim.  If stderr exists, it is also inserted verbatim.

### Keyword arguments

Pandoc code attribute syntax allows keyword arguments of the form `key=value`,
with spaces (*not* commas) separating subsequent keys.  `value` can be
unquoted if it contains only letters and some symbols; otherwise, double
quotation marks `"value"` are required.  For example,
```
{.python key1=value1 key2=value2}
```
Codebraid adds support for additional keyword arguments.  In some cases,
multiple keywords can be used for the same option.  This is primarily for
Pandoc compatibility.

* `session`={string} — By default, all code for a given language is executed
  in a single, shared session so that data and variables persist between code
  chunks.  This allows code to be separated into multiple independent
  sessions.

* `hide`={`expr`, `code`, `stdout`, `stderr`, `all`} — Hide some or all of the
  elements that are displayed by default.  Elements can be combined.  For
  example, `hide=stdout+stderr`.  Note that `expr` only applies to `.cb.expr`
  or `.cb.nb` with inline code, since only these evaluate an expression.

* `show`={`expr`, `code`, `stdout`, `stderr`, `none`} — Override the elements
  that are displayed by default.  `expr` only applies to `.cb.expr` or
  `.cb.nb` with inline code, since only these evaluate an expression.
  Elements can be combined.  For example, `show=code+stdout`.  Each element
  displayed can optionally specify a format from `raw`, `verbatim`, or
  `verbatim_or_empty`.  For example, `show=code:verbatim+stdout:raw`.

    - `raw` means interpreted as Markdown.
    - `verbatim` produces inline code or a code block, depending on context.
      Nothing is produced if there is no content (for example, nothing in
      stdout.)
    - `verbatim_or_empty` produces inline code containing a single
      non-breaking space or a code block containing a single empty line in the
      event that there is no content.  It is useful when a placeholder is
      desired, or a visual confirmation that there is indeed no output.

  `expr` defaults to `raw` if a format is not specified.  All others default
  to `verbatim`.

* `line_numbers`/`numberLines`/`number-lines`/`number_lines`={`true`, `false`}
  — Number code lines in code blocks.

* `first_number`/`startFrom`/`start-from`/`start_from`={integer or `next`} —
  Specify the first line number for code when line numbers are displayed.
  `next` means continue from the last code in the current session.

* `complete`={`true`, `false`} — By default, code chunks must contain complete
  units of code (function definitions, loops, expressions, and so forth). With
  `complete=false`, this is not required.  Any stdout from code chunks with
  `complete=false` is accumulated until the next code chunk with
  `complete=true` (the default value).

* `outside_main`={`true`, `false`} — This allows code chunks to overwrite the
  Codebraid template code.  It is primarily useful for languages like Rust, in
  which code is inserted by default into a `main()` template.  In that case,
  if a session *starts* with one or more code chunks with `outside_main=true`,
  these are used instead of the beginning of the `main()` template.
  Similarly, if a session *ends* with one or more code chunks with
  `outside_main=true`, these are used instead of the end of the `main()`
  template.  If there are any code chunks in between that lack `outside_main`
  (that is, default `outside_main=false`), then these will have their stdout
  collected on a per-chunk basis like normal.  Having code chunks that lack
  `outside_main` is not required; if there are none, the total accumulated
  stdout for a session belongs to the last code chunk in the session


