tripplilley
commented
1 year ago This might be a bit tricky to implement depending on the availability of a good Java rst parser.
A Sphinx extension would be a more idiomatically correct way to do this. Sphinx's included doctest extension is a good starting place. Writing Sphinx Extensions will give context.
I realize it's Python and y'all are a Java shop, but... ❤️
Right now there is nothing to enforce that documentation examples are actually valid Smithy models. While somebody might run an example through validation when they initially commit it, things can skew over time. Case in point: #295. Ideally we should have a linter, run by CI, that extracts all those examples and runs them through validation. It should also find examples that have IDL and AST formats side by side and assert that they're equal.
There is a minor downside here in that examples will need to be a little more verbose. Right now we exclude parts that don't matter for the purpose of the example, but that often results in something that isn't a valid model by itself.
This might be a bit tricky to implement depending on the availability of a good Java rst parser.