2 ms·
It's all about the tooling. I wrote my own for iommi where the html output of some code gets saved in a defined place, and then the finished documentation page
by boxed 3y ago
It's all about the tooling. I wrote my own for iommi where the html output of some code gets saved in a defined place, and then the finished documentation page embeds that html in an iframe. It's not only WAY WAY easier to maintain than a bunch of screenshots, but I found a ton of issues with the documentation after I made it so it runs all the examples and I can look at the output.
example: https://docs.iommi.rocks/en/latest/cookbook_forms.html https://docs.iommi.rocks/en/latest/cookbook_forms.html
corresponding documentation/tests: https://github.com/iommirocks/iommi/blob/master/docs/test_doc_cookbook_forms.py https://github.com/iommirocks/iommi/blob/master/docs/test_do...
my evil hack to get this working: https://github.com/iommirocks/iommi/blob/master/make_doc_rsts.py https://github.com/iommirocks/iommi/blob/master/make_doc_rst... and https://github.com/iommirocks/iommi/blob/master/iommi/docs.py https://github.com/iommirocks/iommi/blob/master/iommi/docs.p...
- btown 3y agoThat's brilliant! https://github.com/scientific-python/pytest-doctestplus https://github.com/scientific-python/pytest-doctestplus seems to be similar working in the opposite direction, using the documentation source as the single location for test code. I like your approach better and wish there was more support for that pattern more generally!
- boxed 3y agoI started with that approach actually. It turned untenable after a while. It's just much nicer to have the documentation just a part of your normal test suite without any preprocessing. That also means you get coverage in the normal way too.