Add runnable unittest marker for ddox - fixes #137

[wilzbach]

Literally the simplest solution for #137 - whenever I tried to wrap the magic --- it broke the comment or led to the same result as here:

<section>
    <h3>Example</h3>
    <p>
        <span class="dlang_runnable"></span>
    </p>
    <pre class="code">
...

Maybe my Ddoc skills aren't that well, but OTOH a similar hack is used for dlang.org.
However, @s-ludwig if you have a smarter solution - please let me know ;-)

1. How can I add a test? I didn't see any script that executes the stuff in tests
2. Should I provide default definition for this marker or should we better place this in the ddox.doc file at dlang.org

[s-ludwig]

Thanks for tackling this! I just tried to quickly verify this locally, and it basically worked with last_decl["comment"] ~= format("Example:\n%s$(DDOX_UNITTEST \n---\n%s\n---\n)\n", comment.strip, source); and DDOX_UNITTEST defined as "DDOX_UNITTEST": "<span class=\"unittest\"></span>\n$0" - wrapping the whole code block resulted in invalid nesting of HTML tags, though (of course it would have to be <div> instead of <span> in that case anyway).

But I'd still favor the wrapping macro for the increased flexibility (being able to add prologue and epilogue at the same time). Maybe it also makes sense to pass the name of the unit test function to the macro as the first argument, so that it can be used as a unique identifier.

The definition for DDOX_UNITTEST should be in https://github.com/dlang/dlang.org/blob/master/std-ddox.ddoc. In the vanilla DDOX project it wouldn't really make sense, as this approach for runnable examples is quite specific to dlang.org.

[wilzbach]

and it basically worked with

okay, but that yields the same result as e.g.

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

But I'd still favor the wrapping macro for the increased flexibility (being able to add prologue and epilogue at the same time).

+1 (rebased the PR to your version)

The definition for DDOX_UNITTEST should be in https://github.com/dlang/dlang.org/blob/master/std-ddox.ddoc.

Okay I will make a PR to dlang.org then ;-)
I guess you need to make a new release of ddox for that to work?

[s-ludwig]

Okay I will make a PR to dlang.org then ;-)
I guess you need to make a new release of ddox for that to work?

Yes, will do immediately!

[s-ludwig]

Okay, 0.15.17 is up and includes the change.