found the documentation

[darkn3rd]

To document or not to document, that is the question!

I found the documentation embedded in the code, way cool! Is there an auto-gen tool that can scoop up the class name, desc, and example into a markdown or something? I remember at ChefConf18 hackathon, there was some talk about autogen of docs form these fields, but wasn't sure if this was out or how to get it. I looked at the Rakefile, but there's no task to build docs yet.

[skpaterson]

Good question! I'm not aware of any tool to auto-generate from those fields at this time but that would be great. The longer term plan is hopefully to fold inspec-gcp into inspec core and so docs will eventually be built with this InSpec documentation process to be consistent with existing resources. If it would be useful in the short term, a task to build the docs is certainly something that could be explored.

[clintoncwolfe]

(from the inspec core team)

Yes, we are currently working to expand the in-code DSL for docs. For now, writing docs in markdown or ERB-wrapped-markdown is important (to capture the information). I'd advise against implementing a Rake task for the time being; two initiatives (the in-source DSL project, and the versioned docs project) are both likely to impact the doc generation process heavily.

You might want to skip the rarely-used ERB features, and simply write markdown docs; that will make them readable and linkable on github, at least.

[skpaterson]

Good suggestion - I'll convert those docs to markdown after #18 is completed.