Discussion: How will we teach literate programming in Python?

[joelostblom]

I am not familiar with teaching literate programming outside of the notebook format. With .py files, I don't know any great ways of mixing text and code for longer data narratives. Spyder and a few other editors has the notion of code cells, which help divide the code into blocks dedicated to certain functionality and makes it easier to run just these sections at a time. However, there is no native support for markdown and any annotations would have to be done in comments which is unsatisfactory for anything more than a sentence.

The best way I can think of doing this is what I mentioned in the publishing issue, which is to use the python script just for figure generation and then reference these from a markdown file where the data narrative is described. See that issue for details on this option.

Other options include Jupytext, a command line tool that extend the code cell notion to also include cells of other types, such as markdown. It is mostly used to convert Jupyter Notebooks into plain text formats such as .Rmd and there is no easy way to work with it together with Spyder automatically without the command line. I will say that if anyone is looking for nicer notebook version control or want to edit notebooks in an IDE, this tool is pretty slick. It does all the conversions under the hood and only requires the .ipynb files for outputs (like the .html in R), so I am currently working with my Jupyter Notebooks directly in .Rmd format, quite fun and git add -p is a dream!

Another option is pweave (inspired by sweave) which is an RMarkdown-like project. However, pweave is currently unmaintained as the author moved to julia. There used to be support for pweave in spyder via the reports plugin, but its latest commit was in 2017; and the main dev said they will have a look at it after spyder 4 is out. The current best (only?) GUI-driven way to use the project is via atom with hydrogen.

Similar efforts include codebraid, which is a multi language version of pweave/Rmarkdown that according to its own feature list is the best. It is a command line tools that is meant to run in-place of pandoc (which is part of its internals) and I have not seen any GUI that supports it.

How good is Python support via reticulate and in the RStudio IDE in general? Is there a Python console? The more I think of this, the more that sounds like the best solution outside Jupyter Notebooks for allowing mixing text with code and giving good publishing options.

[lwjohnst86]

We'll use Jupytext, Maddy showed a very convincing and cool demo on it! Closing.