
Stitch – A small Python library for writing reproducible reports in Markdown - okket
https://pystitch.github.io/
======
cmontella
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](https://github.com/witheve)

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

------
todd8
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](https://www.jstatsoft.org/article/view/v046i03)

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

[3] [http://leoeditor.com](http://leoeditor.com)

~~~
whorleater
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!

------
todd8
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](https://news.ycombinator.com/item?id=10069748)

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

~~~
todd8
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...](https://www.amazon.com/Computers-Typesetting-B-TeX-
Program/dp/0201134373/ref=sr_1_7?ie=UTF8&qid=1472702616&sr=8-7&keywords=computers+%26+typesetting)

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

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

------
chriswarbo
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](http://chriswarbo.net/projects/activecode/index.html)

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

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

------
nrjames
This reminds me of Sweave for R.

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

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

------
daveguy
The github code repository:

[https://github.com/pystitch/stitch](https://github.com/pystitch/stitch)

