On Sat, Aug 9, 2014 at 5:42 AM, Erik Dalén <[email protected]> wrote:
> > > On 9 August 2014 00:10, Hailee Kenney <[email protected]> wrote: > >> 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. >> > > Regarding the naming, maybe just rename the old rdoc implementation to > puppet rdoc, and make puppet doc point to the new shiny doc generator. > >> 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! >> > > It seems like a decent approach. But for most modules I've found that the > documentation is insufficient in some cases and I need to look at the > source to see what some option will actually do. YARDoc has a "View source" > button at the bottom, but it isn't very well integrated, and for that I > like the two column approach of docco/shocco/pycco etc better, see > http://fitzgen.github.io/pycco/ for an example. > > Also I think it would be nice to be able to write documentation like this: > > # Manage installation of foo > class foo ( > Number $bar, # The value of the bar setting > ) { ... } > > Instead of having to always repeat the parameters (and their type in > puppet 4) in a documentation block, like: > > # Manage installation of foo > # @param bar [Number] The value of the bar setting > class foo ( > Number $bar, > ) { ... } > +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. Nan -- 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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-dev/CACqVBqAjWkAKp_jdZ05U%3D01e94_qbNRaDSx95VeZ%3DkpKGUFhuw%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
