Convert documentation to Puppet Strings format

[Joris29]

Pull Request (PR) description

Update documentation and generate reference with puppet strings.

This Pull Request (PR) fixes the following issues

Followup to #516.

[Joris29]

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

Nice work!

I think the Modules line is about Ruby modules, like here:

puppet-rundeck/lib/puppetx/rundeck/acl.rb

Line 3 in 97a6a14

module PuppetX

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.

[kenyon]

You can also remove the Setup and Reference sections from the README.

[Joris29]

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

[kenyon]

Nice! Thanks. I will do a squash on merge.