Project

General

Profile

Feature #101

Add ability to view puppetdoc documentation

Added by Frank Sweetser over 9 years ago. Updated over 6 years ago.

Status:
Closed
Priority:
Normal
Assignee:
Category:
Puppet integration
Target version:
Difficulty:
Triaged:
No
Bugzilla link:
Pull request:
Team Backlog:
Fixed in Releases:
Found in Releases:

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.

Associated revisions

Revision a67b0923 (diff)
Added by Paul Kelly about 9 years ago

Fixes #101 - Generate rdoc files and html links on the puppetclasses page

Rewite rdocs if required by the prepare phase
Incorporate Fank Sweetser's :: patch
Incorporate a url_helper suggested by Ohad
Added a new interface via links on the supported environments list

History

#1 Updated by Ohad Levy over 9 years ago

  • Category set to Puppet integration

so this seems to be "simple" if:

  1. you generate a pupeptdoc per environment
  2. you link directly to the class - e.g. puppetdoc_dir/classes/classname.html
  3. 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?

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

#3 Updated by Ohad Levy over 9 years ago

  • Target version set to 0.1-4

#4 Updated by Ohad Levy over 9 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

#5 Updated by Paul Kelly over 9 years ago

  • Status changed from New to Assigned
  • Assignee set to Paul Kelly

#6 Updated by Paul Kelly over 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.

#7 Updated by Paul Kelly over 9 years ago

  • Status changed from Feedback to Ready For Testing

#8 Updated by Ohad Levy over 9 years ago

  • Assignee changed from Paul Kelly to Frank Sweetser

Hi,

Do you think you could test this patch?

Many thanks,
Ohad

#9 Updated by Frank Sweetser over 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 over 9 years ago

Found another issue - nested classes (ie, 'ntp::client') need to have the double colons turned into slashes to generate valid URLs. Simple patch attached.

#11 Updated by Ohad Levy over 9 years ago

  • Assignee changed from Frank Sweetser to Paul Kelly

#12 Updated by Paul Kelly over 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

#13 Updated by Paul Kelly over 9 years ago

rebased against develop@95131ca23a6b28e295be839964f9663b0e07c559
cleaned up whitespace
set default_scope to order by name for puppetclasses
fixed tests

#14 Updated by Paul Kelly over 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,

#15 Updated by Paul Kelly about 9 years ago

  • Branch set to feature/101-view-puppetdocs

Rabased

#16 Updated by Paul Kelly about 9 years ago

  • Status changed from Feedback to Ready For Testing
  • % Done changed from 0 to 100

#17 Updated by Ohad Levy about 9 years ago

  • Status changed from Ready For Testing to Closed

Also available in: Atom PDF