On Sat, Aug 9, 2014 at 5:42 AM, Erik Dalén <erik.gustav.da...@gmail.com> wrote:
> > > On 9 August 2014 00:10, Hailee Kenney <hai...@puppetlabs.com> 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 puppet-dev+unsubscr...@googlegroups.com. 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.
