Jira (PDOC-254) @hiera section for putting example hiera

[Eric Putnam (JIRA)]

Eric Putnam created an issue

Puppet Strings / PDOC-254 @hiera section for putting example hiera Issue Type: New Feature Assignee: Unassigned Created: 2018/05/21 1:46 PM Priority: Normal Reporter: Eric Putnam Add a @hiera tag for puppet files so example hiera can be displayed with yaml syntax. Add Comment

This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93)

[Henrik Lindberg (JIRA)]

Henrik Lindberg commented on PDOC-254

Re: @hiera section for putting example hiera How would that work? Why is a tag required?

Add Comment

[Bernard Bondos (JIRA)]

Bernard Bondos commented on PDOC-254

Re: @hiera section for putting example hiera

that would be nice to have, so i can better document usage of hiera keys that are not based on module parameters. tag would be great to get it out in json as separate key.

Add Comment

[Matthias Baur (JIRA)]

Matthias Baur commented on PDOC-254

Re: @hiera section for putting example hiera

What needs to be changed is this line --> https://github.com/puppetlabs/puppet-strings/blob/59428718a0ecbb639027aefc3cc40b7ade89e390/lib/puppet-strings/markdown/templates/classes_and_defines.erb#L41 I see to options: 1. Make it configurable in the @example 2. Add a @hiera tag as suggested by Eric Putnam

Add Comment

[Sean Millichamp (JIRA)]

Sean Millichamp commented on PDOC-254

Re: @hiera section for putting example hiera

I like the idea of a @hiera tag. Though making the example syntax style configurable might be more flexible. I actually think that there may be two Hiera-related opportunities here: 1) Documenting keys which are used in lookup() calls which aren't class parameters similar to the style of "@param". Maybe the data type could even be sussed out of the lookup() call parameters, if listed. 2) Documenting example Hiera YAML blocks as they would look in the file. This would be more in keeping with the @example tag. To Henrik Lindberg's question, I'd like to think the value of #1 is self-evident. From a user standpoint "lookup()" only based keys are still parameters which are part of the interface. For #2 most of my day-to-day user base is very familiar with making changes in Hiera/YAML, but they are not as familiar (in some cases, not at all) with Puppet class syntax and examples shown in Puppet class parameter declaration style wouldn't be nearly as meaningful/useful to them.

Add Comment

[Matthias Baur (JIRA)]

Matthias Baur commented on PDOC-254

Re: @hiera section for putting example hiera

For #2 most of my day-to-day user base is very familiar with making changes in Hiera/YAML, but they are not as familiar (in some cases, not at all) with Puppet class syntax and examples shown in Puppet class parameter declaration style wouldn't be nearly as meaningful/useful to them. Exactly the same for us!

Add Comment

[Henrik Lindberg (JIRA)]

Henrik Lindberg commented on PDOC-254

Re: @hiera section for putting example hiera

I would prefer if there was a @lookup tag, and that it would work more or less as @param, i.e. you can state a data type and what it means. Then any yaml examples (or whatever is needed given whichever backend examples are provided for, that just uses the @example tag. The reason I want "lookup" as tag rather than "hiera" is that it is "lookup" everywhere else (function, CLI, "Automatic Parameter Lookup", etc.) - and that "hiera" is a particular implementation of lookup. What remains is to decide on what the output looks like - should for example all @param be included again in the lookup section and mixed with those that are explicitly looked up?

Add Comment

[Sean Millichamp (JIRA)]

Sean Millichamp commented on PDOC-254

Re: @hiera section for putting example hiera

In my perfect world I'd like @lookup (and yes, you're right, a much better name than @hiera) to look and work more or less exactly like @param, near/in the param section. But maybe just auto-tagged with a "Not available as a class parameter" type message. I don't like the re-including all the @param docs again, it seems unnecessarily verbose bordering on confusing for a class with a very large set of parameters. Even with a @lookup tag, I still feel that there is a need for an additional @example-style tag for YAML-syntax highlighted groups of keys for specific use cases and complex behaviors requiring setting multiple keys to achieve specific results.

Add Comment

[Henrik Lindberg (JIRA)]

Henrik Lindberg commented on PDOC-254

Re: @hiera section for putting example hiera

Sean Millichamp Isn't it possible to just do @example This is a bit of yaml ```yaml key: value ``` (code}

Add Comment

[Matthias Baur (JIRA)]

Matthias Baur commented on PDOC-254

Re: @hiera section for putting example hiera

Henrik Lindberg Nope it isn't, it breaks syntax highlighting. We currently use the following as a workaround: # @summary My example summary # # #### Examples # # ```yaml # classes: # - my_example_class # ``` # # @param first_parameter Very important parameter I'm sure why it works, but i shows up in the generate documentation.

Add Comment