Repository navigation
[DevHub] WordPress – testable, interactive documentation proposal #730
Description
From my conversation with @adamziel
Stale documentation is an issue. But what if CI would raise alarm bells every time a Pull Request “breaks” the documentation? Even better – what if the documentation pages were interactive (like this Tag Processor tutorial)? The documentation would never go stale again AND the developers would enjoy a much better learning experience!
Technically, there are two parts to it:
Automatically testing the documentation
Rendering interactive documentation in the browser
The only thing they have in common is a source material that has a code snippet, a recipe to run it, and an expected output. That’s also the most challenging part – figuring out how to write that document. Perhaps a markdown document with some custom syntax? For example:
Here's how you can add an alt="" attribute to an tag:
<runnable>
<dependencies>
<file source="wordpress" path="wp-includes/html/wp_html_text_span.php" />
<file source="wordpress" path="wp-includes/html/wp_html_tag_processor.php" />
</dependencies>
<code lang="php">
<?php
$html = '<img src="https://github.com/husky.jpg">';
$p = new WP_HTML_Tag_Processor( $html );
if ( $p->next_tag() ) {
$p->set_attribute( 'alt', 'Husky in the snow' );
}
echo $p->get_updated_html();
</code>
<expected-output>
<img alt="Husky in the snow" src="https://github.com/husky.jpg">
</expected-output>
</runnable>
It’s a bit xml-y but perhaps it would do.
The CI handler would load the dependencies, run the snippet, and raise alarm bells if any PR leads to a different-than-expected output. So it’s just like a unit test.
The browser documentation would render a small code editor with a “Run” button and a result preview.
Activity
zzap commentedon Mar 31, 2023
Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.
adamziel commentedon Mar 31, 2023
I don't see any technical blockers. CI is already there, it would just need a way to parse the documentation files. The only missing part is a well-designed format that would:
I would really love to build on top of an existing, established format but I haven't found any prior art on this.
I looked for "Testable documentation" "documentation CI" "linking documentation with code" and so on. I mixed that with PHP, Python, and a few other languages and the closest match were inline test cases inside PHPDoc strings.
This can't be the first time this idea came up – what am I missing?
adamziel commentedon May 13, 2023
Mdx format could be the missing piece: WordPress/wordpress-playground#323
[-]WordPress – testable, interactive documentation proposal[/-][+][DevHub] WordPress – testable, interactive documentation proposal[/+]