Metadata-Version: 2.1
Name: codebraid
Version: 0.1.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 command-line program that enables executable code in
Pandoc Markdown documents.  Using Codebraid can be as simple as adding a class
to your code blocks, 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+ code.  Support for Julia, R, Rust, and
several other languages is nearly ready for release.

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

[View example HTML output](http://htmlpreview.github.com/?https://github.com/gpoore/codebraid/blob/master/examples/python.html), or [download it](https://github.com/gpoore/codebraid/blob/master/examples/python.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 -f markdown -t markdown test.md
```

Output:

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

## Installation and requirements

Installation:  `python3 setup.py install` (or on some Windows installations
and Arch Linux, `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 `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>`.


## 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 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.

* `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.  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.

  The default format for all commands is `verbatim`, except for `.cb.expr` and
  inline `.cb.nb`, which default to `raw`.

* `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.


