Generate tutorials from code comments

[Aeva]

This is really a feature for whisperscope, but I'll describe it here as it pertains to documentation of m.grl.

The idea is that some comments can be marked such that they exist as a cohesive block that is part of the page's content; and that everything between it and the next content block is itself a code block. Consider:

// [~]
// some *markdown* here
//

// some really simple code:
var a = 1; // variable assignment

// [~]
// some more markdown here
//

The output would look something like this:

<div class="prose">
  Some <em>markdown</em> here
</div>
<div class="code">
// some really simple code:
var a = 1; // variable assignment
</code>
<div class="prose">
Some more markdown here
</div>

Visually, this might be styled such that the 'prose' blocks are paper cutouts laid on top of a long column with the code printed on it. Or it might be styled as a page of text with the code in boxes. In either case, css should be used to preserve the code's formatting.

There could also be a custom markdown tag to allow for the demo to be included in the generated document via an iframe.

This should probably be used for generating the sphinx docs for now, though it could also be used with some kind of templating system to output something entirely different.

[wijnen]

For pretty annotated code, that is useful. For generating tutorials, I think it would be good to also allow marking some parts of the code as "not part of the tutorial" (meaning they will be ignored when rendering). While having all the code is often useful to understand things well, it is possible that some parts are omitted because they make it needlessly complex (in which case they arguably shouldn't be in there anyway) or the tutorial is advanced and they are too trivial to repeat (which is a good reason for skipping them).

It would probably be nice to allow the viewer to see all the hidden parts anyway, if they want to.

[Aeva]

I think this is a good idea. My main inspiration for this are the NeHe tutorials that I learned OpenGL 2.x from, so long ago - they have a base code which demonstrates the feature and then the article highlights the different parts of the code and explains what they do. Later articles build off of the ones before them, so they only highlight what is new.

I like the idea of being able to show/hide sections. I'll add some kind of directive for de-emphasizing comments and code that were explained elsewhere.