search

voxpupuli / puppet-rundeck

Module for managing the installatation and configuration of the rundeck orchestration tool
https://forge.puppet.com/puppet/rundeck
MIT License
39 stars 128 forks source link

Convert documentation to Puppet Strings format #519

Closed Joris29 closed 1 year ago

Joris29 commented 1 year ago

Pull Request (PR) description

Update documentation and generate reference with puppet strings.

This Pull Request (PR) fixes the following issues

Followup to https://github.com/voxpupuli/puppet-rundeck/pull/516.

Joris29 commented 1 year ago

@kenyon Hello so i took my time to go trough all documentation and added missing docs or update docs to be able to generate reference with puppet strings.

The reference was generated but the report is not 100% yet and i also need to remove stuff from the readme but i wanted your view on why the puppet strings is not yet at 100%.

This is the report:

[vacoj@lx-20202056 puppet-rundeck]$ puppet strings generate --format markdown
[warn]: Missing @return tag near lib/puppet/parser/functions/validate_rd_policy.rb:9.
Files                     21
Modules                   3 (1 undocumented)
Classes                   1 (0 undocumented)
Constants                 0 (0 undocumented)
Attributes                0 (0 undocumented)
Methods                   10 (9 undocumented)
Puppet Classes            11 (0 undocumented)
Puppet Data Types         0 (0 undocumented)
Puppet Data Type Aliases  2 (0 undocumented)
Puppet Defined Types      6 (0 undocumented)
Puppet Providers          0 (0 undocumented)
Puppet Functions          1 (0 undocumented)
Puppet Tasks              0 (0 undocumented)
Puppet Plans              0 (0 undocumented)
Puppet Types              0 (0 undocumented)
 70.59% documented
kenyon commented 1 year ago

Nice work!

I think the Modules line is about Ruby modules, like here: https://github.com/voxpupuli/puppet-rundeck/blob/97a6a14c6a2465cfa779191a8c3e048f580c57e7/lib/puppetx/rundeck/acl.rb#L3

Same for Methods, I think it is referring to the Ruby methods in acl.rb being undocumented. I think we can ignore that for now.

By the way, you can do bundle install and then bundle exec rake strings:generate:reference to generate REFERENCE.md.

Joris29 commented 1 year ago

@kenyon I generated the refs with the command provided but same result I guess we can ignore it for now.

[vacoj@lx-20202056 puppet-rundeck]$ bundle exec rake strings:generate:reference
[warn]: Missing @return tag near lib/puppet/parser/functions/validate_rd_policy.rb:9.
Files                     21
Modules                   3 (1 undocumented)
Classes                   1 (0 undocumented)
Constants                 0 (0 undocumented)
Attributes                0 (0 undocumented)
Methods                   10 (9 undocumented)
Puppet Classes            11 (0 undocumented)
Puppet Data Type Aliases  2 (0 undocumented)
Puppet Data Types         0 (0 undocumented)
Puppet Types              0 (0 undocumented)
Puppet Defined Types      6 (0 undocumented)
Puppet Functions          1 (0 undocumented)
Puppet Plans              0 (0 undocumented)
Puppet Providers          0 (0 undocumented)
Puppet Tasks              0 (0 undocumented)
 70.59% documented

I also updated the readme properly and moved the examples to the readme.

Do you want me to squash all commits into one or should i reword some commits or is it fine like it is now?