Hi all,
TL;DR `puppet doc` is broken with the future parser and we need a replacement. Our primary focus is getting manifest documentation supported in Puppet 4. From there, support for other aspects of Puppet will be added. Thoughts?
Due to incompatibility with the new Puppet parser, we are looking into a replacement for the puppet doc feature. For those of you not familiar, `puppet doc` is a command which allows you generate documentation for Puppet manifests. It’s also used internally to generate documentation for other aspects of Puppet itself. For manifests, it uses RDoc to generate some HTML which can be used in a browser based off the information available from .pp files.
However, as mentioned, the current implementation of `puppet doc` does not work with the future parser, meaning that in Puppet 4 it will be completely broken with respect to Puppet code and manifests. It will however still support documentation for Puppet itself. Since we know that being able to quickly generate documentation for one’s Puppet ecosystem is a valuable tool, we don’t want to lose support for it in Puppet 4. However, there are a lot of issues with the current RDoc implementation, namely that RDoc is not actually meant to be extended to support the Puppet language and that it changes drastically between different versions of Ruby, meaning that puppet doc can break horribly between Ruby versions (the transition from 1.8.7 to 1.9.3 was especially terrible). In addition to the issues caused by RDoc, there are some problematic aspects of the implementation itself, especially its relationship with the parser. So, considering there’s lots of room for improvement in the current RDoc implementation, this seems like a great opportunity to start over with something new. This way we can build a tool that is all around better and more sustainable.
Right now, Charlie Sharpsteen has an awesome prototype which uses YARDoc instead of RDoc. If you want to check out the prototype, it’s available on GitHub. We will soon be migrating the project to the Puppet Labs organization and using it as a starting point. This raises an important question, however: what should we call this new documentation tool? It doesn’t seem right to call it ‘puppet doc’ since that’s a preexisting tool which will continue to coexist with the new one for a while. We also don’t want to call it ‘puppet yardoc’ since YARDoc is really just an implementation detail which we may move away from. We could really use some suggestions on what to call this feature, so please chime in if you have any suggestions.
This seems to be a much better approach since YARDoc is meant to be extended to handle documentation for other languages. We’re planning to build off this prototype to create a new documentation tool which will be contained in a separate module and will just use the Abstract Syntax Tree produced by the Puppet parser rather than being tied directly into the parser itself. The new tool will produce two outputs: human-readable HTML which may be viewed in a browser, and a structured machine-consumable output intended primarily for internal use to generate documentation about Puppet. While more outputs may be supported in the future, these are the two we’ve decided to start with. In terms of input, it will support comments written in both Markdown and RDoc, although Markdown is encouraged. RDoc support remains for backwards compatibility purposes and because it is easy to support with YARD.
Due to the time crunch with the release of Puppet 4 fast approaching, we’ve decided to narrow our scope to ensure that we at least have a replacement for manifest documentation to go with Puppet 4. Then we can expand and begin to document other parts of Puppet, such as functions. In addition to focusing on manifest documentation, the initial release will also include only HTML output. The first pass will also be a little different in terms of implementation. We will begin by using YARD’s builtin Code Objects to construct a Registry from the ASTs produced by the Puppet and Ruby parsers. After an initial release however, we will design our own Document Object Model and the structured output mentioned above. Our hope is that the initial implementation will help to inform what these should look like.
We would really like to hear any input anyone has regarding this new documentation tool. Does this seem like the right approach? Are there other output formats that should eventually be supported? What should we call it? What don’t you like about the current tool so that we don’t repeat that mistake? If you have any suggestions, concerns, or questions, please chime in!
Hi all,
TL;DR `puppet doc` is broken with the future parser and we need a replacement. Our primary focus is getting manifest documentation supported in Puppet 4. From there, support for other aspects of Puppet will be added. Thoughts?
Due to incompatibility with the new Puppet parser, we are looking into a replacement for the puppet doc feature. For those of you not familiar, `puppet doc` is a command which allows you generate documentation for Puppet manifests. It’s also used internally to generate documentation for other aspects of Puppet itself. For manifests, it uses RDoc to generate some HTML which can be used in a browser based off the information available from .pp files.
However, as mentioned, the current implementation of `puppet doc` does not work with the future parser, meaning that in Puppet 4 it will be completely broken with respect to Puppet code and manifests. It will however still support documentation for Puppet itself. Since we know that being able to quickly generate documentation for one’s Puppet ecosystem is a valuable tool, we don’t want to lose support for it in Puppet 4. However, there are a lot of issues with the current RDoc implementation, namely that RDoc is not actually meant to be extended to support the Puppet language and that it changes drastically between different versions of Ruby, meaning that puppet doc can break horribly between Ruby versions (the transition from 1.8.7 to 1.9.3 was especially terrible). In addition to the issues caused by RDoc, there are some problematic aspects of the implementation itself, especially its relationship with the parser. So, considering there’s lots of room for improvement in the current RDoc implementation, this seems like a great opportunity to start over with something new. This way we can build a tool that is all around better and more sustainable.
Right now, Charlie Sharpsteen has an awesome prototype which uses YARDoc instead of RDoc. If you want to check out the prototype, it’s available on GitHub. We will soon be migrating the project to the Puppet Labs organization and using it as a starting point. This raises an important question, however: what should we call this new documentation tool? It doesn’t seem right to call it ‘puppet doc’ since that’s a preexisting tool which will continue to coexist with the new one for a while. We also don’t want to call it ‘puppet yardoc’ since YARDoc is really just an implementation detail which we may move away from. We could really use some suggestions on what to call this feature, so please chime in if you have any suggestions.
This seems to be a much better approach since YARDoc is meant to be extended to handle documentation for other languages. We’re planning to build off this prototype to create a new documentation tool which will be contained in a separate module and will just use the Abstract Syntax Tree produced by the Puppet parser rather than being tied directly into the parser itself. The new tool will produce two outputs: human-readable HTML which may be viewed in a browser, and a structured machine-consumable output intended primarily for internal use to generate documentation about Puppet. While more outputs may be supported in the future, these are the two we’ve decided to start with. In terms of input, it will support comments written in both Markdown and RDoc, although Markdown is encouraged. RDoc support remains for backwards compatibility purposes and because it is easy to support with YARD.
Due to the time crunch with the release of Puppet 4 fast approaching, we’ve decided to narrow our scope to ensure that we at least have a replacement for manifest documentation to go with Puppet 4. Then we can expand and begin to document other parts of Puppet, such as functions. In addition to focusing on manifest documentation, the initial release will also include only HTML output. The first pass will also be a little different in terms of implementation. We will begin by using YARD’s builtin Code Objects to construct a Registry from the ASTs produced by the Puppet and Ruby parsers. After an initial release however, we will design our own Document Object Model and the structured output mentioned above. Our hope is that the initial implementation will help to inform what these should look like.
We would really like to hear any input anyone has regarding this new documentation tool. Does this seem like the right approach? Are there other output formats that should eventually be supported? What should we call it? What don’t you like about the current tool so that we don’t repeat that mistake? If you have any suggestions, concerns, or questions, please chime in!
On Aug 8, 2014 5:15 PM, "Hailee Kenney" <hai...@puppetlabs.com> wrote:
>
> Right now, Charlie Sharpsteen has an awesome prototype which uses YARDoc instead of RDoc.
I see that "YARD does not impose a specific markup"[1] and I cannot tell from Charlie's prototype which markup is intended -- I would hope that one of them would be picked as a standard and I would be happiest with something that uses some flavor of Markdown.
I understand that more semantic markup is desired, but I find the proliferation of wildly incompatible text markup formats frustrating. Variations in Markdown implementations[2] are bad enough; having to mentally switch to RDoc format to write module documentation causes much wailing and gnashing of teeth.
1. http://rubydoc.info/gems/yard/file/docs/GettingStarted.md
2. Gollum uses Github-flavored with some wiki-specific extensions; Jekyll by default uses either RedCarpet (1.x) or Kramdown (2.x), which have incompatible code blocks; then there's the GFMD that Github renders *.md with; we use Atlassian Stash internally, which renders some flavor, etc.
To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-dev/ls60bk%24omb%241%40ger.gmane.org.
--
You received this message because you are subscribed to the Google Groups "Puppet Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to puppet-dev+unsubscribe@googlegroups.com.
Thanks for all the feedback everyone! Going back to the issue of naming, I have a list of suggestions I've collected that I wanted throw out there for discussion:puppet strings (this seems to be a popular choice)
puppet readmepuppet guidepuppet usage
puppet doxpuppet watson (or potentially another muppet-related name)puppet pub / puppet pubs (as in publication)puppet tomepuppet infopuppet eyes
Thoughts on any of these?--
Hailee KenneyAssociate Developer, Puppet LabsRegister by September 8th to take advantage of the Final Countdown —save $149!
--
You received this message because you are subscribed to the Google Groups "Puppet Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to puppet-dev+...@googlegroups.com.To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-dev/CALdYGa8yKMpf8K1p-RgbY18paQv1rooc%3DNFBW1_X-0NddMUaRQ%40mail.gmail.com.
On Tue, Aug 12, 2014 at 10:19 AM, Hailee Kenney <hai...@puppetlabs.com> wrote:
puppet readmepuppet guidepuppet usageThese three seem like they would be confused with "puppet help" too easily
On Aug 12, 2014 1:00 PM, "Daniele Sluijters" <daniele....@gmail.com> wrote:
>
> Please don't use `dox`. It's like a teenager who wasn't taught enough English in school, or simply doesn't care, to know that the accepted plural of doc is docs, not dox, dawg.
I have to agree, if for a different reason -- "dox" has taken on rather more specific connotations than just a foulspelling of "docs".
+1, anything dry that makes documentation less of a chore. There's a lot of things we can already infer from the module layout, and I like docco style embedding of documentation because you need to reference the puppet source code in a lot of cases.
--
You received this message because you are subscribed to the Google Groups "Puppet Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to puppet-dev+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-dev/6aa1a498-9a57-4c72-bd5d-3279de6731b7%40googlegroups.com.