Jira (PDOC-254) @hiera section for putting example hiera
Title: Message Title 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.
Jira (PDOC-254) @hiera section for putting example hiera
Title: Message Title 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 This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93) -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-bugs+unsubscr...@googlegroups.com. To post to this group, send email to puppet-bugs@googlegroups.com. Visit this group at https://groups.google.com/group/puppet-bugs. To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-bugs/JIRA.252028.1526935563000.35046.1559748600624%40Atlassian.JIRA. For more options, visit https://groups.google.com/d/optout.
Jira (PDOC-254) @hiera section for putting example hiera
Title: Message Title 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 This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93) -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-bugs+unsubscr...@googlegroups.com. To post to this group, send email to puppet-bugs@googlegroups.com. Visit this group at https://groups.google.com/group/puppet-bugs. To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-bugs/JIRA.252028.1526935563000.34851.1559738400478%40Atlassian.JIRA. For more options, visit https://groups.google.com/d/optout.
Jira (PDOC-254) @hiera section for putting example hiera
Title: Message Title 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 This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93) -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-bugs+unsubscr...@googlegroups.com. To post to this group, send email to puppet-bugs@googlegroups.com. Visit this group at https://groups.google.com/group/puppet-bugs. To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-bugs/JIRA.252028.1526935563000.34836.1559736720225%40Atlassian.JIRA. For more options, visit https://groups.google.com/d/optout.
Jira (PDOC-254) @hiera section for putting example hiera
Title: Message Title 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 This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93) -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-bugs+unsubscr...@googlegroups.com. To post to this group, send email to puppet-bugs@googlegroups.com. Visit this group at https://groups.google.com/group/puppet-bugs. To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-bugs/JIRA.252028.1526935563000.34804.1559733780239%40Atlassian.JIRA. For more options, visit https://groups.google.com/d/optout.
Jira (PDOC-254) @hiera section for putting example hiera
Title: Message Title 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 This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93) -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-bugs+unsubscr...@googlegroups.com. To post to this group, send email to puppet-bugs@googlegroups.com. Visit this group at https://groups.google.com/group/puppet-bugs. To view this discussion on the web visit
Jira (PDOC-254) @hiera section for putting example hiera
Title: Message Title 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 This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93) -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-bugs+unsubscr...@googlegroups.com. To post to this group, send email to puppet-bugs@googlegroups.com. Visit this group at https://groups.google.com/group/puppet-bugs. To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-bugs/JIRA.252028.1526935563000.34717.1559728080491%40Atlassian.JIRA. For more options, visit https://groups.google.com/d/optout.
Jira (PDOC-254) @hiera section for putting example hiera
Title: Message Title 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 This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93) -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-bugs+unsubscr...@googlegroups.com. To post to this group, send email to puppet-bugs@googlegroups.com. Visit this group at https://groups.google.com/group/puppet-bugs. For more options, visit https://groups.google.com/d/optout.
Jira (PDOC-254) @hiera section for putting example hiera
Title: Message Title Henrik Lindberg commented on PDOC-254 Re: @hiera section for putting example hiera How would that work? Why is a tag required? Add Comment This message was sent by Atlassian JIRA (v7.7.1#77002-sha1:e75ca93) -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-bugs+unsubscr...@googlegroups.com. To post to this group, send email to puppet-bugs@googlegroups.com. Visit this group at https://groups.google.com/group/puppet-bugs. For more options, visit https://groups.google.com/d/optout.
Jira (PDOC-254) @hiera section for putting example hiera
Title: Message Title 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)
