Adding setup info to code blocks in asciidoc, part 1

Note: No solutions to this problem listed, in this part 1. Just pondering how stuff might work..

Starting to think about whether it is possible to add extra information to a code block in asciidoc/asciidoctor. Code blocks can already have a source entry, such as this:

[source,apache]
----
<VirtualHost *:80>
...
</VirtualHost>
----

Here, two values "source" and "apache" are associated with the code block, and hence pygments will know how that this block is source code and should be rendered in apache configuration file syntax.

Now, I would like to add information on setup code to run, before running the code in a code block. This should work for different languages, not just say javascript or python, like for instance write out the code and the setup code to a JSON file that can be processed further. Let's say there is a piece of python code that reads:

[source, python]
----
fab = bar.foo(baz="bletch")
fab.send()
----

It is pretty clear that that code will not run by itself. So it would be nice to have some setup code specification, that could be used to produce a test suite from the code. Something like this:

[source,python, setup=flum_setup]
----
fab = bar.foo(baz="bletch")
fab.send()
----

where flum_setup could be a name that a test framework can use to look up what needs to be in place before testing that the piece of code works.

Loking at Sphinx, a documentation system for python, you can do this in reStructuredText, an alternative to asciidoc:

.. testsetup:: [group]

A setup code block. This code is not shown in the output for other builders, but executed before the doctests of the group(s) it belongs to.

sphinx.ext.doctest – Test snippets in the documentation — Sphinx 1.3.1+ documentation

Looking at asciidoc it seems like a lot is controlled from .conf files, that contain sections and name-value pairs, where values are written in some syntax with elements of regular expressions. So, how do you define what can get written into the block metadata (the inside brackets stuff preceding the block)?

This link seems to be a start:

Chapter 32. Block Element Definitions It contains info on something called "options", defined as "A comma delimited list of element specific option names.". It seems to look something like this in a source file:

[options="foo,fab,bletch"]

There is also something called posattrs where you can do something like this in a conf document:

posattrs=attribution,citetitle,favorite_dish

and these below values would get assigned to the predefined variables in a block:

["Mr foo", "fab farming", "flum pudding"]

Ok if/when i figure that out, it would be time to define back-end that writes the code blocks and their metadata to JSON.

Actually, looking back at the source code of sphinx.ext.doctest (sphinx/doctest.py at master · sphinx-doc/sphinx), maybe it would be quicker to just clone that extension, and make it write to JSON instead of executing the code blocks in python. In that way the syntax could be used with any language. And in that case I'd abandon asciidoc (short love affair) and start using reStructuredText.