Markdown output does not currently distinguish between the group headings for the table of contents and group headings in the actual content. This change adds a 'Table of Contents' heading and changes group headings to bold text to make it much more clear that you're looking at the table of contents.
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.
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 table_of_contents template was already too bulky and redundant and recognizing public and private components was only going to make it worse. This refactors the toc template and the toc class to use a generic outline for all components.
If there is a class, type, or function with no information documented but is pulled in by some fluke or tag we don't support, do not give it its own section
This implements the two remaining tags and removes the author tag. Had to do some deeper plumbing because options per function signature were not being passed along from YARD
This implements the author tag. We also claim to support the 'raise' and 'option' tags, but I don't know that we need to. This also consolidates some code in base.rb and adds docs
This change does a few things:
1. Fixes up new api handler to return the stuff we want
2. Adds all the logic to parse YARD registries into markdown
3. Adds templates for markdown
4. Changes Face cli to use a --format option that can be used for either
markdown or json
* install the correct CAs in the correct places so windows can install gems
* use a gem_command abstraction to find the correct puppet gem exe
[skip ci]
Because Puppet 4 is typed, parameter type information can
be automatically determined without any explicit documentation
in @param tags. However, users may desire to do so anyway for
consistency. This commit allows @param tags to include a [type]
in Puppet 4 code. Strings will emit a warning if the documented
type does not match the actual type. In such an event, the incorrect
documented type will be ignored in favor of the real one.
Previously, overload objects were not displaying their tags when
they had no docstring text. This was due to an issue in the overload
`to_hash` method, which prevented the tags from being serialized when
the dispatch had no top-level text. This commit updates that logic
so that the tags will always be included in the hash if they exist.
Eric Putnam