Documenting terraform can be difficult. Most of the time what ends up happeing is you have a README.md in each terraform module that's suppose to describe what the module does. That never ends up actually being the case.
But Sphinx and other tools do a good job of enabling docs-as-code it's a whole thing. And the gold standard of docs as code is Sphinx (my opinion). It does a great job of documenting various types of code, but especially python.
So someone came along and wrote sphinx-terraform specifically a cool guy named Charles . I've used that tool to document a lot of terraform.
However, there was a problem. There was a common pattern I'd be running across in companies. Somewhere out there there's a collection of mildly related terraform modules all in the same repositoty. They should be documented. They never are. Ever time it's updated it's important, too important to delay with documentation. So this multi-terraform repo simply grows and grows with content and new ever less related content. To that end I wanted a way to "auto" document modules based on a common schema.
So that's what sphinx-terrafomr-ch attempts to be. This is a rewrite that I did with the help of claude. There's some vibe'd stuff in there. But I'm hoping that this will be worthwhile to all of you. There's a documentation page describing the options. But I think it's notable that there's the ability to define a map of your terraform projects and to generate a report for an individual report. Reports generate as markdown and get parsed into sphinx's docutils format by myst-parser. I hope this is helpful for all of you out there.
Future work, I'm looking around to see if I can do more around calling out module usage and potentially diagramming sphinx modules by default. Might not be viable, might be viable. Please make an issue if you feel there's something that could be added.