This updates various docs in the project.
* Get rid of MAINTAINERS
* Update JSON.md with tasks and plans
* Fix some weirndess in the README
* Polish CONTRIBUTING.md
Discovered that this hack was finding broken links and then replacing all instances of the link text in the README. This led to a lot of non-links being affected. This patch works harder to match only actual links and works as far as I can tell.
Currently there is no evidence in REFERENCE.md itself that it was generated and should not be edited. This adds a comment in the markdown, so as not to disrupt its rendered appearance but still communicate to the user when editing that the file is generated.
The 'features' key in the resource api expects an array of feature names. Currently, if you run strings on a resource api type that specifies features, it falls over because it doesn't know what to do with an AST node of type :array. Further, the method that throws the error is looking for an undefined variable called 'parameters'. This removes the odd conditional that calls 'parameters' and adds a method that returns an array of the array contents that may be passed to features. Features are not currently sent to the renderer, but now Strings will be able to handle any array it comes across in an rsapi type.
When using `puppet strings server`, resources with names containing '::' end up 404ing from the left bar. This is because strings namespaces these objects but YARD does not when building URLs.
e.g. foo::bar's url should be /doc/foo/puppet_classes/foo/bar.html but
ends up instead being doc/foo/puppet_classes/foo_3A_3A_bar.html because
of YARD's url encoding. This is a monkey patch, courtesy @domcleal, that
decodes the urls back so that they are namespaced correctly.
Currently, Plans are not being included in the table of contents in the
markdown output. This is because Plans were not being passed to the
table of contents renderer. This adds Plans to the renderer and updates
tests accordingly.
Some variants of markdown do not convert atx-style headers correctly
unless they are surrounded by blank lines. This commit adds blank lines
to increase chances of rendering when using those variants while still
maintaining compatibly with variants that do not require the surrounding
blank lines. Also increases readability when viewing the raw markdown
file.
Currently, if the user is documenting a Puppet 4 type custom function and they try to use the return_type method without also including an @return tag, Strings will throw an error. This is caused by the function handler trying to add a type to a return tag on the function object that doesn't exist. To fix the problem, if you are using return_type, the handler will now add an empty return tag first if one does not exist.
Currently, Puppet Strings only supports Puppet Tasks. Since Plans are
sort of connected to Tasks, it seemed right that Strings should also
support Plans. That and Plans are a thing that needs to be documented.
First, the Puppet[:tasks] setting needs to be set to add the 'plan' keyword to the Puppet Parser's lexicon, so this sets it in the Strings parser if the setting exists. If it does not exist and Puppet.version is less than 5.0.0, Strings will error out.
Second, processing for the Plans themselves is set up. Plans are very
similar to other Puppet objects like defined types and classes, so this
involved some serious copy-pasta.
Third, all the template/to_hash scaffolding for the different outputs is in place (HTML,
JSON, Markdown).
Yey.
Currently, if a user attempts to document the title or name params, Strings will throw a warning saying that these parameters are missing from the class/type. Of course, they aren't, they just may not be explicit. This removes the warning if the param name is 'name' or 'title'.
First, there were some rspec problems we originally connected to directory naming (e.g. 'yard'), but now we think it's a possible bug in rspec (https://github.com/rspec/rspec-core/issues/2184). this removes the markdown_spec.rb test that was both triggering the bug and, as it turns out, is an unnecessary test.
Reverted some of the changes made to the rsapi handler during markdown
output work. Those changes were made because of a typo in the spec
tests, so the typo has been fixed and most of the handler returned to
its original state.
This gets rid of test cells for old versions of ruby (< 2.1.9) and old versions of puppet (< 4) and also updates the test command to run all 100+ unit tests instead of a whopping 27 that rake spec runs
Currently, puppet-strings does not know how to generate documentation
for Puppet Tasks. This does all the work to add support for Tasks
including a new JSON parser, a task handler, task statement, and task code
object. Basically, Strings reads the JSON using the native ruby json
parser and sends values through in a way it understands. It is only
passing json key/value pairs through, nothing is happening with tags at
this time. You can now document Tasks and generate HTML, Markdown, or
JSON output.
The version of github changelog generator we want to use requires a
version of Ruby we can't yet guarantee. This reverts all the plumbing
for gcg while still committing the changelog
jbondpdx