How should we author and publish tutorials and how-to guides containing code?

[caro401]

Currently, there's 2 approaches to authoring tutorials that contain code and its output.

• Jupyter notebooks example
• mkdocs directives in a markdown file example

We need to consider

• ease of authoring - we hope researchers in the team will write these tutorials
• maintainability - these tutorials really need to be accurate and work reliably, there's little more demoralising for an end user than a getting started guide that they can't get to work. At the very least each tutorial needs to document exactly what plugins and versions it uses.
• ease of publishing - assuming the docs will be published in a sveltekit site, whatever we do needs to be render-able by javascript in some way, ideally without having to call any python directly.

It would seem that writing the text for tutorials in markdown in some way would be preferable - both solutions already use this, people seem happy writing it and it doesn't seem to have inherent technical problems. Markdown is well-supported within svelte/kit, either by mdsvex or the remark/rehype ecosystem.

I don't really have any solutions about how to do the code side of things.

Something like executing a whole jupyter notebook and rendering it out to markdown or html via nbconvert before sveltekit picks it up might be a possible approach, but I'm not sure how to handle the python environment required to execute it.

Something related to the JSON files produced for #3 might be a thing to consider - if the tutorial focusses on a particular plugin, within the plugin itself, get the python code and return values at each step in a JSON file too, along with metadata about what versions of everything got used. But then I'm not clear on how that would get into the main docs repo, or what authoring such a tutorial would look like.

@makkus do you have any thoughts on this?

[makkus]

I'm not sure about the best approach here, jupyter might be ok for very code-centric stuff, but personally I'd prefer markdown.

The way I did the 'getting started' thing with all it's code examples and cli input/output was to call macros from within the markdown text, and include the rendered output in the rendered final document. The main reason I did that was to have a tested and up-to date document, becaues if the rendering fails, that means some of the included examples broke in CI. Plus, no need to copy and past result output whenever a command changes.

In the context of svelte, I am not sure what the best approach is. But we could figure out a solution where we either pre-run the examples in a ci step, and store the output in a json file or similar, with unique keys to access them. Or we could have a minimal kiara service running that would be called with the example code, and would return the result, to be included in the rendered doc?

Some way of running all included examples is sometihng I have good experience with, and would definitely recommend for the advantages I stated earlier.