stitch¶
stitch is a library for making reproducible reports. It takes a markdown source file, executes the code chunks, captures the output, and stitches the output into the destination file.
Those familiar with knitr and RMarkdown will recognize it as a python clone of those great libraries. It’s also heavily influenced by knitpy.
While stitch
is written in python, it can be used for
any of the dozens of Jupyter
kernels.
Examples¶
See the examples
site for a side-by-side
comparison of the markdown source and rendered output.
Links to a more complicated document rendered in various formats
is also provided.
Install¶
At the moment, the name stitch is taken on PyPI via an inactive project. You can install stitch from PyPI via
pip install knotr
I know, it’s confusing.
I’ve filed a claim for stitch
on PyPI, but I think the people working that support queue are over-worked.
Once that gets processed, I’ll put it up on conda-forge as well.
If you need a mnemonic, it’s “I want knitr, but not the one written in R.
Also I wanted to confuse R users.
And knots are kind of like a buggy version of knits.
But to be clear the package name and command-line tool is stitch
.
You’ll also need pandoc>=1.18.
Either use your system package manager, or use the pypandoc
provided on conda-forge, which includes
pandoc.
Supported Python Versions¶
Stitch itself, the library, is only compatible with python 3.
However, you can compile documents with a python2 environment, as
long as you have a Python 2 kernel installed (see jupyter kernelspec list
).
Usage¶
You write a markdown file, and include code chunks that look like
```{kernel_name, [chunk_name], **kwds}
# your code here
```
The kernel_name
is required (see jupyter kernelspec list
).
The chunk_name
is optional; it controls things like the name assigned
to plots if they’re saved to disk.
The supported keyword arguments are
- eval: bool, whether to execute the code chunk
- echo: bool, whether to include the input code chunk in the output
More options will be added.
The command-line interface is essentailly the same as pandocs. For the most part you call
stitch input_file.md -o output_file.html
You can use -t
for the output type, or infer it from the file extension
of -op
.
All other options are passed through to pandoc.
stitch defines a few new options that control stitch-specific features
--no-standalone
--no-self-contained
What’s in a Name?¶
The name stitch
has a couple meanings. Like R’s knit
, we are
taking a source document, executing code chunks, and knit
ing or
stitch
ing the output back into the document.
The second meaning is for stitch
bringing together a bunch of great
libraries, minimizing the work we have to do ourselves. stitch
uses
- Pandoc markdown parsing and conversion to the destination output
- jupyter, specifically jupyter-client for managing kernels, passing code to kernels, and capturing the output
- pandocfilters for converting code-chunk output to pandoc’s AST
- pypandoc for communicating with pandoc
- click for the command-line interface.
stitch
itself is fairly minimal. The main tasks are
- processing code-chunk arguments
- passing the correct outputs from the jupyter kernel to pandocfilters
- assembling all the chunks of text, code, and output in a sensible way
- making things look nice
Contents: