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, ) { ... } Sometimes you have long descriptions of the parameters though and then being able to put them in a documentation block is nicer, so ideally both should be supported. That being said I definitely prefer regular YARDoc to Rdoc. -- Erik Dalén -- 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/CAAAzDLc7EAyQHuAnd4BDVTwZkm%2BjU4xUgefz7n4tJ2gPk%2BfA6g%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
