running the code snippets from the documentation

[singuliere]

@jeffwecan wrote

On the sphinx front, I've actually spent the bulk of my hvac development time over the past month or so implementing doctest after receiving a good deal of documentation typo reports. So I'd recommend checking out that extension if you're interested. I have been pretty pleased with it thus far! https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html

[singuliere]

I'll definitely use that, thanks for the hint :-)

[singuliere]

Since these are shell snippets, doctest is not the right fit. Writing Technical Documentation with Sphinx, Paver, and Cog suggests cog would be a good fit. But it looks like it has not been updated in years.

[singuliere]

autorun or shell-doctest are almost good but not maintained. I've used cram and the experience was good, in the past. But there is no sphinx extension and it's not been updated in three years.

[singuliere]

@jeffwecan unless you have a suggestion I'm tempted to close this as won't fix. I don't like the idea that example code is untested but if there is no tooling the best we can do is to carefully test manually.

[singuliere]

Ned Batchelder says he still uses cog "to make all my presentations."

[jeffwecan]

Actually yeah in hindsight that makes a lot of sense. I would categorize this as a nice to have in the first place. So if its not immediately implementable it is fine to close out imho.

[singuliere]

Let's keep this for later 👍

[singuliere]

For the record cog was recently upgraded and improved

[briantist]

#17