Add ability to view puppetdoc documentation
It would great if you were able to view formatted puppetdoc documentation for each class. The ideal would be to have available the full documentation in the Settings -> Puppet Classes page, and a shorter summary (title plus first paragraph, maybe?) on any page where classes are associated with other entities.
#1 Updated by Ohad Levy over 9 years ago
- Category set to Puppet integration
so this seems to be "simple" if:
- you generate a pupeptdoc per environment
- you link directly to the class - e.g. puppetdoc_dir/classes/classname.html
- you ignore the nodes data (hopefully you are using external nodes with foreman anyway).
so one approach would be to create another settings in configs/settings.yml and define puppetdoc_dir where:
the actual puppet doc would be at:
#2 Updated by Frank Sweetser over 9 years ago
Sounds good to me. Foreman is obviously most useful when used an an external node classifier, so I don't think it's entirely unfair to skip over node docs. Plus, if you're switching from nodes.pp over to foreman as an external node source, you already have to manually shuffle over settings and class assignments anyway, so copying over the comments too shouldn't be a big deal.
#6 Updated by Paul Kelly about 9 years ago
- Status changed from Assigned to Feedback
There is a provisional implementation of this code on branch feature/101 on my github.
We must discuss this as it is not complete
Maybe you can answer these and other questions
1) How do you access rake's --verbose flag from within a rake task?
2) Does/Should the user have a concept of a current environment.
#9 Updated by Frank Sweetser about 9 years ago
I gave it a quick trial run today, and it looks pretty good to me. I just had a few minor comments.
- The environment selection page looks a little awkward if you have fewer than four environments. Ideally, if you only have a single environment (like I do) it would skip the selection page altogether and just send you to the correct page.
- This is technically a puppet issue, but I wasn't able to run the document creation task until I patched puppetrun to not pass the --force-update option to rdoc, since my version (stock centos 5.4) didn't support it.
- I have my docroot pointing at foreman (it's running on a single purpose VM), so in order to make the puppetdoc output viewable I had to have them dumped in the public directory of foreman. This may be worth mentioning in the documentation.
Other than that, this patch gets my vote.
#10 Updated by Frank Sweetser about 9 years ago
- File 0001-Generate-valid-doc-URLs-for-nested-classes.patch 0001-Generate-valid-doc-URLs-for-nested-classes.patch added
Found another issue - nested classes (ie, 'ntp::client') need to have the double colons turned into slashes to generate valid URLs. Simple patch attached.
#12 Updated by Paul Kelly about 9 years ago
The code has been rebased against develop and now incorporates Frank Sweetser's request for a direct link to the rdocs if there is only one environment. I have also applied his patch for the :: issue. Thanks Frank.
I will now add a page to the Wiki for this feature
#14 Updated by Paul Kelly about 9 years ago
- Status changed from Ready For Testing to Feedback
Fixed the fgrep issue and other points raised.
Ohad, do you think that the list of supported environments, on the puppetclasses page, could be replaced with a list of links rather than text. The links could point at the documentation and be one click closer. This is different to all other controllers but might be acceptable if the column heading is changed,