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 <https://github.com/Sharpie/puppet-puppet_yardoc>. 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! -- Hailee Kenney hai...@puppetlabs.com Associate Developer, Puppet Labs *Join us at PuppetConf 2014 <http://www.puppetconf.com/>, September 20-24 in San Francisco* *Register by September 8th to take advantage of the Final Countdown <https://www.eventbrite.com/e/puppetconf-2014-tickets-7666774529?discount=FinalCountdown> * *—**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+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-dev/CALdYGa8DcyQbMHrEcXkShGKuF2yNhvfBar%3D42RGD_c3toP%3D0qw%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
