Feature #101
closed
Add ability to view puppetdoc documentation
Description
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.
Files
Updated by Ohad Levy over 14 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:
puppetdoc_dir/#{environment}/classes/${class}.html
any thoughts?
Updated by Frank Sweetser over 14 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.
Updated by Ohad Levy about 14 years ago
- Target version changed from 0.1-4 to 0.1-5
I'm pushing this to the next release, as I'm a bit out of time and would like to get the bug fixes out
Updated by Paul Kelly about 14 years ago
- Status changed from New to Assigned
- Assignee set to Paul Kelly
Updated by Paul Kelly about 14 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.
Updated by Paul Kelly about 14 years ago
- Status changed from Feedback to Ready For Testing
Updated by Ohad Levy about 14 years ago
- Assignee changed from Paul Kelly to Frank Sweetser
Hi,
Do you think you could test this patch?
Many thanks,
Ohad
Updated by Frank Sweetser about 14 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.
Updated by Frank Sweetser about 14 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.
Updated by Ohad Levy about 14 years ago
- Assignee changed from Frank Sweetser to Paul Kelly
Updated by Paul Kelly about 14 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
Updated by Paul Kelly almost 14 years ago
rebased against develop@95131ca23a6b28e295be839964f9663b0e07c559
cleaned up whitespace
set default_scope to order by name for puppetclasses
fixed tests
Updated by Paul Kelly almost 14 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,
Updated by Paul Kelly almost 14 years ago
- Status changed from Feedback to Ready For Testing
- % Done changed from 0 to 100
Applied in changeset a67b092319ec685ce08e4f222f9d4e0398c13297.
Updated by Ohad Levy almost 14 years ago
- Status changed from Ready For Testing to Closed