Can someone summarize state-of-the-art workflows for generating presentable finished documents?

Hello. I apologize if this question isn’t well-formed for the forums.

I am wondering what the state of the art is for mixed plot/results-and-text documents intended for display as HTML (web) or PDF.

In the old days, before I ever used Julia, I had two workflows that I would have used to answer this question relative to R:

  1. Write your document in R Sweave / eventually in knitr, .Rmd, compile it to HTML, post to web
  2. Write your document in R Sweave / eventually in knitr .Rmd, compile to TeX then pdflatex to PDF.

Since then I’ve been overwhelmed by the apparent explosion in options. I think this is really cool; it seems like more things offer more support for more other embedded things. E.g., a Jupyter notebook can have Markdown and LaTeX and even both embedded R and Julia. The Pluto.jl platform has built-in interactivity. And this is only scratching the surface.

What I am wondering is if someone far more knowledgeable about (a) the breadth of these solutions and (b) the state of the art can offer a somewhat opinionated summary of the current state of the art workflow for various tasks.

For example, suppose my main desire is to write a blog post that is primarily words for a non-technical audience, but include a couple of Julia-generated graphs. A valid claim would be “don’t try to embed anything, just generate your graphs outside the post and write the post in text, copy the images in.” Another might be “Don’t be silly, such-and-such workflow is the perfect workflow for this,” e.g. write it in some Julia analogue of R markdown (of which I’m unaware) and only in a couple places will I have to fence off some Julia that generates the graph.

Suppose separately my main desire is to write a PDF that is primarily math-heavy. One valid claim would be “write it in TeX and name your included images intelligently, write the Julia script to generate those images”; another would be “here is the right workflow for generating TeX->PDF outputs from a mixed Julia-and-TeX file.”

I hope this question makes sense. I’m open to pushback on it; essentially my challenge here is that I think I’ve failed to keep up with all the developments in integrated document, online, notebook formats, etc.

Thank you!

2 Likes

Not trying to answer your whole question. But just so you know, R Markdown is actually a misnomer, since it supports about 40 languages including Julia.

2 Likes

Indeed I did not know that. Cool–thanks!

This is one of the reasons why all my Julia blog posts are written in RMarkdown. :blush:

3 Likes

And may I follow up by asking–do you have a certain tooling that you like around this, e.g. do you typically write documents in VSCode and knit to preview in HTML, or do you use one of those notebooks-embedded-in-VSCode formats, or … ?

1 Like

If I have to document a simulation or the results of running julia and the math behind it, I will sometimes use a library I wrote to programmatically create Latex output, including math , figures and tables etc to generate either a slide deck or even a full report.

I can even write the report in Lyx and then simply include the latex output from my simulations.
There are similar capabilities for matlab and python, e.g.

pyt2tex, etc.
pytexit — pytexit 0.3.4 documentation .

It’s not too hard to do it on your own. I’d release it but unfortunately I don’t control it’s license.

I use neovim together with tmux to be able to send code to the console. Then i have a Hugo serve running which compiles on every change and it shows up in my browser. For PDF the workflow is the same except i use a different output and viewer.

This is what I do, mainly because otherwise

  1. rebuilding a whole site would take enormous amounts of time,
  2. I would have to be very organized about manifests etc if I wanted the code to work a couple of years later. With the graphs generated, I always have a backup.

Just to add a few more to the discussion that don’t seem to have been linked directly, there’s:

I’ve probably missed off a couple, but there’s a lot of options, and since generating documents is a pretty broad area, it’s great that we have so many options.

5 Likes