Replacement for puppet doc

[Hailee Kenney]

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! 

--

Hailee Kenney

hai...@puppetlabs.com

Associate Developer, Puppet Labs

Join us at PuppetConf 2014, September 20-24 in San Francisco

Register by September 8th to take advantage of the Final Countdown —save $149!

[Erik Dalén]

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. 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

[Nan Liu]

+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

[Wil Cooley]

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.

Is this intended to be used only in Puppet manifests, or would there be support (in tooling/standards, at least) for using it in Ruby exentions too?

I would also like to express my concern about: "Documentation blocks must immediately precede the documented code with no whitespace." -- I spent several hours that could better have been spent watching Vanilla Sky or Gigli to this little bundle of joy in the current implementation -- particularly the "with no whitespace" bit.

As for names, how about 'moddoc'?

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.

[Henrik Lindberg]

On 2014-09-08 20:32, Wil Cooley wrote:
> On Aug 8, 2014 5:15 PM, "Hailee Kenney" <hai...@puppetlabs.com

> <mailto: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.
>

So far, the idea has been to standardize on a particular preferred
markup based on Markdown with a selection of tags from yardoc. In order
to no force everyone that has invested in writing RDoc documentation to
rewrite all docs in their manifests, we also need to continue supporting
this. However, note that the support for any kind of markup in the
current puppet doc tool is very very limited, and it is really only this
limited set that will be supported going forward. Therefore there is
typically not much markup at all in documentation.

I expect us to exactly specify the markdown and tagging that the new
"puppet doc" tool will support. IMO this specification will be
compatible with Markdown (some defined flavor) and yardoc tags.

> 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.
>
> Is this intended to be used only in Puppet manifests, or would there be
> support (in tooling/standards, at least) for using it in Ruby exentions too?
>

Yes, Since the idea is to be Markdown/Yard compatible.

> I would also like to express my concern about: "Documentation blocks
> must immediately precede the documented code with no whitespace." -- I
> spent several hours that could better have been spent watching Vanilla
> Sky or Gigli to this little bundle of joy in the current implementation
> -- particularly the "with no whitespace" bit.
>

Yeah, hate that for two reasons; a) you may accidentally get
documentation output when you intended a comment, and b) the
documentation may not show up if there is a blank space.

We no longer have to have this rule. It has also been proposed that
comments sequences that start with ## are special. This is important
since it is also proposed that it should be possible to document
parameters on the same line (after the declared element). say

foo ## This is doc for foo

Here the ## are needed if we want it to be possible to write a comment
that is not documentation.

- henrik

--

Visit my Blog "Puppet on the Edge"
http://puppet-on-the-edge.blogspot.se/

[Hailee Kenney]

--
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.

To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-dev/ls60bk%24omb%241%40ger.gmane.org.

For more options, visit https://groups.google.com/d/optout.

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 readme

puppet guide

puppet usage

puppet dox

puppet watson (or potentially another muppet-related name)

puppet pub / puppet pubs (as in publication)

puppet tome

puppet info

puppet eyes

Thoughts on any of these?

[Andy Parker]

On Tue, Aug 12, 2014 at 10:19 AM, Hailee Kenney <hai...@puppetlabs.com> wrote:

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)

I like this one too

 

puppet readme

puppet guide

puppet usage

These three seem like they would be confused with "puppet help" too easily

 

puppet dox

puppet watson (or potentially another muppet-related name)

puppet pub / puppet pubs (as in publication)

puppet tome

puppet info

puppet eyes

Of these I think dox is alright.

 

Thoughts on any of these?

--

Hailee Kenney

hai...@puppetlabs.com

Associate Developer, Puppet Labs

Join us at PuppetConf 2014, September 20-24 in San Francisco

Register 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.

For more options, visit https://groups.google.com/d/optout.

--

Andrew Parker

an...@puppetlabs.com

Freenode: zaphod42

Twitter: @aparker42

Software Developer

Join us at PuppetConf 2014, September 22-24 in San Francisco

Register by May 30th to take advantage of the Early Adopter discount —save $349!

[Daniele Sluijters]

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.

[Nick Fagerlund]

Well, something I've learned over the last four years is that cute names age a lot faster than you'd think. So I'm generally in favor of descriptive ones instead, at least when we're dealing with command -line tools.

And unfortunately, "puppet doc" is pretty much the perfect name for it. :/ So, two things:

1. Can we consider renaming the old tool to puppet rdoc, as suggested earlier? It's always been janky; a rename might actually be a good signal to users that there's now something better.

2. If that's a no-go, we might want to use a temporary name for the new tool, one that shows it will eventually be called puppet doc. Maybe "puppet docplus" or something. Once we think we can get away with killing off the old-school puppet doc, I'd really like to reclaim its name for the improved tool.

Anyway, if we can't use puppet doc:

- puppet strings is all right, though I don't love it. (It's cute, but it's sort of domain-appropriate this time, so I could live with it.)

- new suggestions: "puppet details" or "puppet codex."

On Tuesday, August 12, 2014 10:33:04 AM UTC-7, Andy Parker wrote:

On Tue, Aug 12, 2014 at 10:19 AM, Hailee Kenney <hai...@puppetlabs.com> wrote:

puppet readme

puppet guide

puppet usage

These three seem like they would be confused with "puppet help" too easily

 

I have the same problem with these three.

[Henrik Lindberg]

On 2014-12-08 23:52, Nick Fagerlund wrote:
> Well, something I've learned over the last four years is that cute names
> age a lot faster than you'd think. So I'm generally in favor of
> descriptive ones instead, at least when we're dealing with command -line
> tools.
>
> And unfortunately, "puppet doc" is pretty much the perfect name for it.
> :/ So, two things:
>
> 1. Can we consider renaming the old tool to puppet rdoc, as suggested
> earlier? It's always been janky; a rename might actually be a good
> signal to users that there's now something better.
> 2. If that's a no-go, we might want to use a temporary name for the new
> tool, one that shows it will eventually be called puppet doc. Maybe
> "puppet docplus" or something. Once we think we can get away with
> killing off the old-school puppet doc, I'd really like to reclaim its
> name for the improved tool.
>

I like this approach (renaming the old version "1" tool). IMO the
current (r)doc tool should be deprecated in 3.7 and also be made
available under its new name (puppet rdoc). In Puppet 4.0 we remove the
old name (in wait for the new module / tool to mature and be released as
the new puppet doc).

Thus, you can continue to use 'puppet doc' in the 3x series', and you
can prepare to switch to 4.0 since 'puppet rdoc' will also work in 3.x
and continue to work for a subset of puppet in 4.0 (I guess until Puppet
5.0).

While we are waiting for the new puppet doc (simply version 2) to mature
and be incorporated back into puppet, we can have a project name for it
that is on the cute side :-)

- henrik

> Anyway, if we can't use puppet doc:
>
> - puppet strings is all right, though I don't love it. (It's cute, but
> it's sort of domain-appropriate this time, so I could live with it.)
> - new suggestions: "puppet details" or "puppet codex."
>
> On Tuesday, August 12, 2014 10:33:04 AM UTC-7, Andy Parker wrote:
>
> On Tue, Aug 12, 2014 at 10:19 AM, Hailee Kenney
> <hai...@puppetlabs.com <javascript:>> wrote:
>
>
> puppet readme
> puppet guide
> puppet usage
>
>
> These three seem like they would be confused with "puppet help" too
> easily
>
>
> I have the same problem with these three.
>

> --
> 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

> <mailto:puppet-dev+...@googlegroups.com>.

> To view this discussion on the web visit

> https://groups.google.com/d/msgid/puppet-dev/2146c62c-b643-4330-85ae-665437a18c7b%40googlegroups.com
> <https://groups.google.com/d/msgid/puppet-dev/2146c62c-b643-4330-85ae-665437a18c7b%40googlegroups.com?utm_medium=email&utm_source=footer>.

> For more options, visit https://groups.google.com/d/optout.


--

[Wil Cooley]

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".

[Craig Dunn]

I also don't like dox, or anything else that is phonetically identical to a real word.

until end_of_time

  no, I said dox, with an 'x', not 'cs'

end
 

--

Enviatics | Automation and configuration management

http://www.enviatics.com | @Enviatics

Puppet Training http://www.enviatics.com/training/

[Jason Antman]

On Sat, Aug 9, 2014 at 11:16 AM, Nan Liu <nan...@gmail.com> wrote:

+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.

Agreed. Back in the 0.25 days at a former employer, I had a wonderful script that would generate manifest docs and publish them to a web server on every push to the repo. That's been much less useful lately, and I'd love to see it work again. +1 for anything that lets me generate useful docs instead of documenting every param in the file header... and then again in README.md.

[Daniele Sluijters]

What Nick, Henrik and Erik said. Rename the old tool, deprecate it and remove it. `puppet doc` is the command that makes sense and that sensible command should do sensible things.

I kinda do like 'codex' though, it has a ring to it.

-- 

Daniele Sluijters

[Hailee Kenney]

--

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.

For more options, visit https://groups.google.com/d/optout.

Alright, so based off the feedback on the naming and some discussion I think we've come to a reasonable solution (that definitely does not involve the word dox).

Essentially we've decided to do what Henrik described above. To summarize, the end goal is to have a situation where when one uses the 'puppet doc' command, it will use the new tool and the old one will be gone completely.This will be a slow process though, since it will take some time to get the new tool to a place where it is functional enough to replace the current one. 

As a result, in the 3.x series, we will allow the current tool to be invoked using 'puppet rdoc', and when 'puppet doc' is called we will provide a warning explaining that it is being renamed, so that people have time to make the switch before Puppet 4. In Puppet 4, using the rdoc command will tell the user that it is deprecated and no longer supports manifest documentation. In addition it will direct them to the new tool (a module) which they can use instead (which will be called something else for a time, puppet string or puppet codex). Then eventually, when the new tool is functionally ready to be a full replacement for puppet rdoc, we will remove the old tool completely and 'puppet doc' will simply run the new tool which will ship with Puppet.