Implement plugin system for extending the functionality

[khos2ow]

Prerequisites

Put an x into the box that applies:

• This issue describes a bug.
• This issue describes a feature request.

For more information, see the Contributing Guidelines.

Description

At the moment there are only 4 fixed printer types, json, markdown document, markdown table and pretty. Although this might be enough for most of use cases but folks might want to have their own printer setup. This can be because of corporate guideline and branding or simply lack of support (e.g. .adoc format)

We still need to iron out the details, but the rough specification is:

• develop the custom plugin in Go (based on the to be written guidelines)
• maintain the plugin life-cycle independent of terraform-docs binary by the community members
• plugins get distributed by the corresponding authors, outside of scope of terraform-docs release
• terraform-docs will look for the plugins in ~/.terraform.d/plugins (TBD)
• normal execution of commands e.g. terraform-docs custom <plugin-name> /path/to/module

Version

The initial target for this is to be implemented in v0.9.0.

[aaronsteers]

I'm very intrigued by this new feature. I've not learned Go yet myself, but since discovering terraform-docs just less than a week ago I've already wrapped in my own Python code so as to customize the output, adding custom headers and footers to the markdown output, and creating an index of all modules in a repo.

Couple questions:

1. Would plugins be required to be written in Go? (I don't know Go yet but otherwise I'd be interested in perhaps authoring a custom Markdown plugin.)
2. Is there any related effort to process multiple modules or creating a master TOC doc? (Totally fine if not, just curious.)

If you are interested, you can see the output of my own wrapper at https://infra.dataops.tk/docs/catalog_index.html

The title on on each item in the index link to a page created by terraform-docs, with custom headers and fooders added. (Ex: https://infra.dataops.tk/catalog/aws/data-lake/)

[khos2ow]

1. I still haven't ironed out all the details for the plugin system, but originally what I had thought was that you write the plugin using Go. It might be actually very simple (most probably only one .go file would be needed) which you need to implement the Format interface:

https://github.com/segmentio/terraform-docs/blob/7a4bc282d814094ad86b7619c31f974e35612929/pkg/print/print.go#L7-L10

and also use go templating to construct the desired format, something similar to what we've already done in markdown document.

2. I haven't thought about this before, but this sounds a little bit out of scope of this tool. We're trying to follow Unix philosophy in terraform-docs as a binary, it should only do one thing, and does it well, so you can build surrounding toolings of your own around it. But to be fair the use case you mentioned sounds interesting and needs to be thought of more.

[aaronsteers]

@khos2ow - Thanks very much for both responses.

1. Thanks for linking to the template sample. That's very helpful, actually. And while I'm not familiar with Go template syntax, this seems like a relatively small lift to pick up and learn.

• That said, have you considered perhaps using a templating tool like jinja2? The advantage of jinja would be that you might be able to accomplish the same end result purely by providing jinja text file templates, not having to add any new "code" per se to integrate for new plugins (avoiding need to compile and ship additional binaries), but instead taking a one or more jinja template files. (Someone put together a pretty cool comparison of jinja and go templates here.)
• Counterpoint to my own case, I can see a "jinja2 plugin" eventually fitting both design patterns - if there's indeed interest in having jinja2 support. 😉 Also, since Jinja is apparently built on python, that might carry with it some python-related dependencies which could be tricky to package into the go library.

2. I agree completely - and given a choice, I'd rather see terraform-docs continue to expand in the plug-in direction than to spread itself too thin with more "website-building" tasks that wrappers can accomplish.