Tofu docs command

[ucfchandra]

OpenTofu Version

OpenTofu v1.7.2
on darwin_amd64

The problem in your OpenTofu project

I would like to automatically generate documentation without going to a separate terraform-docs tool to do so.

Attempted Solutions

Terraform-docs, which works well, but ideally it could be integrated into opentofu

Proposal

Implement a version of terraform-docs that also allows you to include an editable and non-changing description section at the top. Also, please allow it to check .tofu files.

References

Could not find any

[abstractionfactory]

Hello and thank you for this issue! The core team regularly reviews new issues and discusses them, but this can take a little time. Please bear with us while we get to your issue. If you're interested, the contribution guide has a section about the decision-making process.

[apparentlymart]

When considering this request I think it's worth keeping in mind that the core OpenTofu project does not have unlimited resources, and so we need to consider that each new feature we need to maintain creates an opportunity cost against other work.

By encouraging use-cases that can be met by external tools to be implemented that way, we can distribute the overall ecosystem maintenance work more broadly, and folks who are particularly interested in generating documentation can invest in an excellent tool designed specifically for that purpose, as opposed to an integrated tool whose scope would likely be smaller just due to the cost of maintaining larger features.

By this comment I certainly don't mean to say that we absolutely must not add such a feature to OpenTofu, but I think it's important to weigh the costs against the benefits.

It would be helpful if folks who are interested in having such an integrated tool could share reasons why the existing external tool is unsuitable or inconvenient. Perhaps those concerns are significant enough to justify the costs of maintaining it in-tree as proposed here, or perhaps discussion of those concerns would suggest potential improvements to the existing tool that would make it more convenient to use despite being externally-distributed.

---

For example, if discovery were the primary concern then we might instead consider extending the OpenTofu Registry to include an index of useful extension tools maintained by third-parties, and possibly even some way to automatically install them (with signature verification similar to what we have for providers) using a new OpenTofu CLI command.

[SekhReddy]

I believe this opportunity cost is strongly justified in the short and long term given that all codified infrastructure should be documented. As it stands, I use OpenTofu for test driven development and having an actively maintained tool that can assist with documenting .tofu files is of immense value to my day to day work. I believe any developer with deadlines and teammates would have this issue of needing some tool for automated documentation that can be put into CI/CD. I cannot overstate the importance of a well designed component to fulfill this universal need

[abstractionfactory]

I have to agree with @apparentlymart here. A community tool exists and is being maintained as far as I can tell. Implementing community tools, such as docs generators, version managers, etc. in OpenTofu itself means that updates will be slower and bound to OpenTofu versions. It also means that, at the very least, reviewing PRs will fall on the core team, which results in competing for attention with other features that have no viable community alternative.

On this specific issue: OpenTofu currently has over 300k lines of code, which are not architected towards being able to generate documentation. For the purposes of the OpenTofu Registry Search we have created a tofu metadata dump tool that dumps partial module information in JSON, but this tool exposes internal data structures, which is the primary reason why we haven't merged it yet. Building a user-facing tool would require us to put in significant work into stabilizing this functionality. I would estimate that building such a tool would require several person-months of effort.

We have a strong community creating providers, modules and tools, and I believe the right strategy is to let each tool focus on what it does best. If you are in need for this feature, please comment why terraform-docs is not suitable for your use case so we can find a good solution here.

@SekhReddy if you need terraform-docs to support .tofu files, please express your support for this feature here.

[ucfchandra]

Yes, .tofu files is one component. Another one is fixing the description box so the information above the markdown table doesn't get rewritten every time it's generated. Mainly it's the convenience of using the same tool for the entire test-driven, documented IaC workflow.