Allow runnable unittests like on dlang.org

[wilzbach]

Since a couple of days the dlang.org documentation allows to run unittest directly online, see e.g.

https://dlang.org/phobos-prerelease/std_algorithm_searching.html#.minElement

or for more details the PR.

This works because of this ddoc hack that allows to distinguish between unittest examples and full text examples:

DDOC_EXAMPLES  = <span class="dlang_runnable"></span>$(DDOCKEYVAL Examples, $0)

I had a quick look at ddox and it seems that it's not as straight forward to distinguish unittest examples from full-text examples, because unittest examples get converted into full-text examples i:

last_decl["comment"] ~= format("Example:\n%s\n---\n%s\n---\n", comment.strip, source);

@s-ludwig what would be the nicest way to transfer the information that an example is runnable (i.e. originates from a unittest block)?
The quick solution would be sth. similar to the ddoc "hack":

last_decl["comment"] ~= format(`<span class="dlang_runnable">\nExample:\n%s\n---\n%s\n---\n</span>`, comment.strip, source);

[s-ludwig]

What about:

last_decl["comment"] ~= format(`Example:\n%s\n$(D_UNITTEST ---\n%s\n---)\n`, comment.strip, source);

Then D_UNITTEST can be defined to <span ...>$0</span> in std_ddox.ddox. If undefined, it should resolve to just $0 and not cause any changes.

[s-ludwig]

...or maybe rather DDOX_UNITTEST, as it's DDOX specific.

[andralex]

subscribe

[wilzbach]

Then D_UNITTEST can be defined to <span ...>$0 in std_ddox.ddox. If undefined, it should resolve to just $0 and not cause any changes.

Unfortunately that didn't work out as

--- assert(3.among(1, 42, 24, 3, 2)); if (auto pos = "bar".among("foo", "bar", "baz")) assert(pos == 2); else assert(false); // 42 is larger than 24 assert(42.among!((lhs, rhs) => lhs > rhs)(43, 24, 100) == 2); ---

adding a new line leads after D_UNITTEST lead to:

<section><h3>Example</h3>
<p><span class="dlang_runnable"> 
</span></p>
<pre class="code">
assert(3.among(1, 42, 24, 3, 2));
if (auto pos = "bar".among("foo", "bar", "baz"))
    assert(pos == 2);
else
    assert(false);
// 42 is larger than 24
assert(42.among!((lhs, rhs) => lhs > rhs)(43, 24, 100) == 2);
--- </span>
...

Thus PR #138 tries to just go with a marker.

[andralex]

@s-ludwig awesome! how do we update library-prerelease?