3 ms·

Yeah that looks great for a blog post .. . Good luck writing and maintaining that for a real project in the real world

• 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 ago
    That'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 ago
      I 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.
• williamdclt 3y ago
  Many projects maintain different document types in their docs. Of the top of my head: NestJS.
• deleted 3y ago
  [deleted]
• tepitoperrito 3y ago
  see https://documentation.divio.com/adoption.html https://documentation.divio.com/adoption.html