Stitch – A small Python library for writing reproducible reports in Markdown | Hacker News Reader

Stitch – A small Python library for writing reproducible reports in Markdown

pystitch.github.io

178 pointsokket18 comments

I started practicing literate programming recently, and I don't think I can go back to writing code like I used to. So I get excited when I see projects like this. I especially liked the quote by Knuth on the knitr page:

> Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to humans what we want the computer to do.

This is exactly what we're trying to do with Eve [1]. Right now we're commonmark compatible, so we support the same kind of workflow as this project: write markdown as usual, code blocks are executable Eve code. For example, here's an implementation of TodoMVC written as a literate program [2].

[1]: https://github.com/witheve

[2]: http://incidentalcomplexity.com/2016/08/19/todoMVC/

Emacs org-mode supports literate programming too, see [1] and [2]. Also don't forget Leo a programming editor designed around literate programming [3].

[1] https://www.jstatsoft.org/article/view/v046i03

[2] http://orgmode.org/worg/org-contrib/babel/

[3] http://leoeditor.com

We've come full circle, first we had Org-mode as a simple plain text formatting syntax, then we had Org-Babel as a meta-programming language for literate programming.

Now we've got Markdown as a simple plain text formatting syntax, and Juypter/ipython notebooks followed, containing literate programming. Now we're seeing the rise of Markdown based literate programming.

I can't wait for a true meta-programming language to arrive on the level of Org-Babel, that's the biggest selling point of emacs!

Literate programming comes up every so often on HN. Here is a past discussion asking why didn't it catch on, [1]. I like the idea of reproducible reports, the apparent motivation of the OP, which is a bit different emphasis than literate programming.

[1] https://news.ycombinator.com/item?id=10069748

I think that it did catch on, mainly under the form of iPython notebooks.

Yes, the iPython notebooks are great for reproducible reports. Literate programming, as practiced by Knuth, is a little bit different. The program's output, graphs, tables, etc. isn't intermixed with the text as it is in a Jupyer notebook. A literate program is actually documentation and source mixed together in a web file. Two different programs (tangle and weave) can be run over this literate code. One extracts a (LaTeX) document suitable for publication and the other extracts a program (with all of the documentation stripped out) to be fed into a compiler. The best example I know of is Computers & Typesetting, Volume B: TeX: The Program [1], a 624 page book that is a complete exposition on the TeX program, generated by weave; the same web source run through tangle generates the TeX program itself (the typesetting program upon which LaTeX is built out of TeX macros).

Knuth is a fan of this method of program construction. Of course, he is not only a phenomenal programmer; he is a great writer skilled at explaining complex algorithms and code. I can see why literate programming suits him.

[1] https://www.amazon.com/Computers-Typesetting-B-TeX-Program/d...

The idea of literate code seems much more suited to tests telling a story than it does for regular code.

Can someone please explain how this is different than something like Jupyter Notebook? Just a different editing environment, or ...?

Output is the same, though this and knitr are produced by a plain text file rather than in an interactive notebook in your browser.

Pretty neat. I wrote a couple of scripts for Pandoc to do something similar: "panpipe" allows codeblock contents to be piped through arbitrary commands, and "panhandle" allows codeblocks containing Pandoc ASTs to be spliced into the document.

This simple setup is enough to access any programming language or other tool which handles stdio (including the shell, where we can invoke more complicated build tools, etc.)

http://chriswarbo.net/projects/activecode/index.html

Alternatively, you can use Python in RMarkdown with the same syntax.

Cute! It looks a lot like [Pweave](http://mpastell.com/pweave/) too

This reminds me of Sweave for R.

I came here to say this. Although I know a lot of people prefer Python to R.

Or Rmarkdown

Check out knitr.

I have been wanting something like this for awhile--basically knitr in Python. Jupyter/IPython Notebooks are great for interactive stuff, but I'm more interested in being able to weave documentation into modules. Definitely will give this a try.

The github code repository:

https://github.com/pystitch/stitch

Reply on news.ycombinator.com