Add option for including code in compiled html output

[metasoarous]

This would be nice for folks who want the sort of notebook where you can see the code alongside the resulting visualizations etc. Would also potentially open up the possibility of using Oz for code documentation, al a marginalia.

Some questions around this:

• How would you configure style (inline like Jupyter, or off to the side like Marginalia)?
• Seems like you would only show the non hiccup code?
  • Wouldn't want to see (e.g.) the markdown code as both rendered and unrendered
  • Would maybe though want to see the vega specifications
  • What about hiccup generation code?
    • Maybe use the functional form for this?

[jefffriesen]

Lots of possible use cases by different folks but here's my take on it:

1. Regarding inline like Jupyter or off to the side like Marginalia - I don't have strong preference either way. I've used both styles quite a bit and they both work well.

• Agreed not showing hiccup makes the most sense. To state the obvious, you are unlikely to put meaningful data transformations in your hiccup so there's no real need to show the hiccup. Similarly with Markdown: I would think you would render markdown like hiccup without showing source
• Yep, exposing Vega and Vega-lite specs may be the point of the document as a learning tool, since Vega examples are so helpful to learn from. On the other hand, often they will probably be noise when trying to explain complex data transforms with charts and code. I wonder if printing vega specs could be off by default and shown based on metadata set in the calling function?
• Hiccup generation code? Not sure...

[metasoarous]

Thanks for the feedback @jefffriesen!

you are unlikely to put meaningful data transformations in your hiccup so there's no real need to show the hiccup

Agreed; Good point.

I wonder if printing vega specs could be off by default and shown based on metadata set in the calling function?

I think is more or less what I was coming around to, so thanks for confirming.

Hiccup generation code? Not sure...

Sorry; This probably warrants some explanation. In Reagent, a "hiccup" form can use a function/component as the tag, like [fn-returning-hiccup some-data]. This doesn't work in the standard hiccup processor, but does in Oz.

Again, thanks for the feedback!

[metasoarous]

I've been working on this again for the past several weeks, and one question which has come up is whether or not to show the evaluation results of code blocks or not.

If we do, one thing to be careful of is how we handle lazy seqs. This is where clerk's approach of attaching custom renders is somewhat handy. The other way we can go is to just never display anything unless you specify it in a hiccup block, which effectively gives you more nuanced control over how you want things rendered on a case by case basis, but is probably less convenient for "tinkering" and prodding as you work up intuition on a problem.

Other thoughts: I'm rethinking not showing the hiccup blocks by default. I think for folks wanting to use Oz as a notebook tool (closer to a conventional notebook) may more often than not want to see the code that generated the the visualizations and such (and importantly, in this context, the visualizations will be embedded in hiccup as [:vega-lite ...] blocks, so I'd rather be consistent). Easy enough to add an option for turning this off.

[jefffriesen]

I don't have strong opinions on the best approach but this sounds right to me:

may more often than not want to see the code that generated the the visualizations