{"id":695,"date":"2017-03-08T13:18:34","date_gmt":"2017-03-08T13:18:34","guid":{"rendered":"http:\/\/dlang.org\/blog\/?p=695"},"modified":"2021-10-08T11:10:53","modified_gmt":"2021-10-08T11:10:53","slug":"editable-and-runnable-doc-examples-on-dlang-org","status":"publish","type":"post","link":"https:\/\/dlang.org\/blog\/2017\/03\/08\/editable-and-runnable-doc-examples-on-dlang-org\/","title":{"rendered":"Editable and Runnable Doc Examples on dlang.org"},"content":{"rendered":"

Sebastian Wilzbach was a <\/span>GSoC student<\/span><\/a> for the D Language Foundation in 2016 and has since become\u00a0a regular contributor to Phobos<\/a>, D’s standard library,\u00a0<\/span>and dlang.org<\/a>.<\/span><\/em><\/p>\n

\n

This article explains the steps that were needed to have editable and runnable examples in the documentation on dlang.org<\/a>. First, let\u2019s begin with the building blocks.<\/p>\n

Unit testing in D<\/h3>\n

One of D\u2019s coolest features is its unittest<\/code> block, which allows the insertion of testable code anywhere in a program. It has become idiomatic for a function to be followed directly by its tests. For example, let\u2019s consider a simple function add<\/code> which is accompanied by two tests:<\/p>\n

auto add(int a, int b)\r\n{\r\n    return a + b;\r\n}\r\n\r\nunittest\r\n{\r\n    assert(2.add(2) == 4);\r\n    assert(3.add(4) == 7);\r\n}<\/pre>\n
By default, all unittest<\/code> blocks will be ignored by the compiler. Specifying\u00a0-unittest<\/strong> on the compiler’s command line will cause the unit tests to be included in the compiled binary. Combined with -main<\/strong>, tests in D can be directly executed with:<\/p>\n
rdmd -main -unittest add.d<\/pre>\n
If a unittest<\/code> block is annotated with embedded documentation<\/a>, a D documentation generator can also display the tests as examples in the generated documentation. The DMD compiler ships with a built-in documentation generator (DDoc<\/a>), which can be run with the -D<\/strong> flag, so executing:<\/p>\n
dmd -D -main add.d<\/pre>\n
would yield the documentation of the add<\/code> function above with its tests displayed as examples, as demonstrated here:<\/p>\n
\"\"<\/p>\n
Please note that the documentation on dlang.org<\/a> is generated with DDoc. However, in case you don\u2019t like DDoc, there are several other options<\/a>.<\/p>\n
Executing code on the web<\/h3>\n
Frequent readers of the D Blog might remember Damian Ziemba\u2019s DPaste<\/a> – an online compiler for the D Programming language. In 2012, he made the examples on the front page<\/a> of D\u2019s website runnable via his service. Back in those old days, the website of the D Programming language looked like this:<\/p>\n
<\/p>\n
As a matter of fact, until 2015, communication with DPaste was done in XML<\/a>.<\/p>\n
Putting things together<\/h3>\n
So D has a unit test system that allows placing executable unit tests next to the functions they test, the tests can also be rendered as examples in the generated documentation, and there exists a service, in the form of DPaste, that allows D code to be executed on the web. The only thing missing was to link them together to produce interactive documentation for a compiled language.<\/p>\n
There was one big caveat that needed to be addressed before that could happen. While D\u2019s test suite, which is run on ten different build machines<\/a>, ensures that all unit tests compile & run without errors<\/a>, an extracted test might contain symbols that were imported at module scope and thus wouldn\u2019t be runnable on dlang.org. A unittest<\/code> block can only be completely independent of the module in which it is declared if all of its symbols are imported locally in the test\u2019s scope. The solution was rather simple: extract all tests from Phobos<\/a>, then compile and execute them separately to ensure that a user won\u2019t hit a \u201cmissing import\u201d error on dlang.org. Thanks to D\u2019s ultra-fast frontend, this step takes less than a minute on a typical machine in single-core build mode.<\/p>\n
Moreover, to prevent any regressions, this has been integrated into Phobos\u2019s test suite<\/a> and is run for every PR via CircleCi<\/a>. As Phobos has extensive coverage<\/a> with unit tests, we started this transition with a blacklist<\/a> and, step-by-step<\/a>, removed modules for which all extracted tests compile. With continuous checking in place, we were certain that none of the exposed unit tests would throw any errors when executed in the documentation, so we could do the flip<\/a> and replace the syntax-highlighted unit test examples with an interactive code editor.<\/p>\n
Going one step further<\/h3>\n
With this setup in place, hitting the \u201cRun\u201d button would merely show the users \u201cAll tests passed\u201d. While that\u2019s always good feedback, it conveys less information than is usually desirable.<\/p>\n
Documentation<\/a> that supports runnable examples tends to send any output to stdout<\/code>. This allows the reader to take the example and modify it as needed while still seeing useful output about the modifications. So, for example, instead of using assertions to validate the output of a function, which is idiomatic in D unit tests and examples:<\/p>\n
assert(myFun() == 4);<\/pre>\n
Other documentation usually prints to stdout<\/code> and shows the expected output in a comment. In D, that would look like this:<\/p>\n
writeln(myFun()); \/\/ 4<\/pre>\n
I initially<\/a> tried to do such a transformation with regular expressions, but I was quickly bitten<\/a> by the complexity of a context-free language. So I made another attempt<\/a> using Brian Schott\u2019s libdparse<\/a>, a library to parse and lex D source code. libdparse allows one to traverse the abstract syntax tree (AST) of a D source file. During the traversal of the AST, the transformation tool can rewrite all AssertExpressions<\/strong> into writeln<\/code> calls, similar to the way other documentation displays examples. To speak in the\u00a0vocabulary<\/a> of compiler devs: we are lowering<\/em> AssertExpressions<\/strong> into the more humanly digestible writeln<\/code> calls!<\/p>\n
Once the AST has been traversed and modified, it needs to be transformed into source code again. This led to improvements in libdparse\u2019s formatting capabilities (1<\/a>, 2<\/a>).<\/p>\n
The future<\/h3>\n
As of now, there are still a small number of functions in Phobos that don\u2019t have a nice public example that is runnable on dlang.org. Tooling<\/a> to check for this has recently been activated in Phobos<\/a>. So now you can use this tool (make -f posix.mak has_public_example<\/strong>) to find functions lacking public tests and remove those modules from the blacklist<\/a>.<\/p>\n
Another target for improvement is DPaste. For example, it currently doesn\u2019t cache incoming requests, which could improve the performance of executed examples on dlang.org. However, due to the fast compilation speed of the DMD compiler, this \u201cslow-down\u201d isn\u2019t noticeable and is more of a perfectionist wish.<\/p>\n
I hope you enjoy the new \u201cRun\u201d button on the documentation and have as much fun playing with it as I do. Click here<\/a> to get started.<\/p>\n","protected":false},"excerpt":{"rendered":"
Sebastian Wilzbach was a GSoC student for the D Language Foundation in 2016 and has since become\u00a0a regular contributor to Phobos, D’s standard library,\u00a0and dlang.org. This article explains the steps that were needed to have editable and runnable examples in the documentation on dlang.org. First, let\u2019s begin with the building blocks. Unit testing in D […]<\/p>\n","protected":false},"author":16,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[12,9,20],"tags":[],"_links":{"self":[{"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/posts\/695"}],"collection":[{"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/users\/16"}],"replies":[{"embeddable":true,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/comments?post=695"}],"version-history":[{"count":5,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/posts\/695\/revisions"}],"predecessor-version":[{"id":702,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/posts\/695\/revisions\/702"}],"wp:attachment":[{"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/media?parent=695"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/categories?post=695"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dlang.org\/blog\/wp-json\/wp\/v2\/tags?post=695"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}