Commit Graph

202 Commits

Author SHA1 Message Date
Eric Putnam d4ca490d1b
(maint) display Plans in markdown table of contents
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.
2018-04-03 13:37:47 +01:00
John Lyman 6ba0350928 (PDOC-233) Simplify logic for white space formatting of summary
Instead of specifying white space after each conditional, just add a
blank line at the end of the conditional similar to the `function.erb`
template.
2018-03-30 13:02:59 +00:00
John Lyman ca26677cad (PDOC-233) Make markdown white space formatting consistent
Replace arbitrary double blank lines with a single blank lines.
2018-03-30 13:02:59 +00:00
John Lyman d9065e6f2e (PDOC-233) Increase chances of markdown rendering correctly
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.
2018-03-30 13:02:35 +00:00
Hunter Haugen 6eec1544f7
Merge pull request #168 from eputnam/_pdoc228
(PDOC-228) puppet plan support
2018-03-29 10:22:50 -07:00
Eric Putnam baf000b07e
(PDOC-229) fix error with return_type and @return
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.
2018-03-29 08:48:52 -07:00
Eric Putnam da5cad7cb1
(PDOC-228) puppet plans support
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.
2018-03-27 09:59:20 -07:00
Hunter Haugen e37c8b70ae
Merge pull request #167 from eputnam/pdoc36
(PDOC-36) hack to fix README links in generated HTML
2018-03-26 17:03:39 -07:00
Hunter Haugen 414d124d18
Merge pull request #166 from eputnam/pdoc192
(PDOC-192) remove warning for title/name
2018-03-26 17:02:26 -07:00
Hunter Haugen 5407e4e48d
Merge pull request #155 from eputnam/missing_doc_warn
(maint) add condition for misleading warning
2018-03-26 16:39:03 -07:00
Eric Putnam c56ee788b5
(PDOC-192) remove warning for title/name
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'.
2018-03-22 16:07:24 -07:00
Eric Putnam 37cfe49f95
(PDOC-36) hack to fix README links in generated HTML 2018-03-22 15:39:38 -07:00
Hunter Haugen 67f249c8ea
Merge pull request #164 from eputnam/update_travis
(PDOC-223) prepare travis for dropping old version support
2018-03-22 13:35:29 -07:00
Eric Putnam be444fa6ad
(PDOC-223) revert rsapi changes and remove markdown test
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.
2018-03-22 11:35:37 -07:00
Eric Putnam 738275b9e7
(PDOC-206) support for Puppet Tasks
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.
2018-03-19 11:37:00 -07:00
Ewoud Kohl van Wijngaarden 9728d1004a
(PDOC-224) Handle --emit-json(-stdout) again 2018-03-01 18:28:48 +01:00
Eric Putnam dde16375d0
(maint) actually update rake task 2018-02-27 16:32:33 -08:00
Eric Putnam 784c32c979
(maint) update rake tasks 2018-02-26 15:36:28 -08:00
Hunter Haugen 378c01a719
Merge pull request #157 from eputnam/pdoc-184_2
(maint) do not display name if there is nothing to display
2018-02-26 14:13:31 -08:00
Eric Putnam 65bfdaf1de
remove displayed tag business 2018-02-26 13:50:19 -08:00
Eric Putnam 6923d9e18c
(maint) update table of contents
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.
2018-02-26 13:10:30 -08:00
Eugene Piven 4db84c81e5 Fix return type matching for Puppet functions 2018-02-23 13:56:55 +03:00
Eric Putnam 09a5d3e4ff
(maint) change template logic and add test 2018-02-22 16:07:39 -08:00
Eric Putnam 5a283c2212
(maint) do not display name if there is nothing to display
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
2018-02-22 11:21:06 -08:00
Eric Putnam 1316975826
(PDOC-184) revised cli
`puppet generate` behavior remains unchanged
`puppet generate --format markdown` now defaults to writing to
REFERENCE.md and will accept an override from --out
`puppet generate --format json` defaults to printing to stdout but will
accept the --out param
2018-02-20 12:26:05 -08:00
Eric Putnam 4ea43e03aa
re-add test for Puppet 3 function 2018-02-16 10:57:12 -08:00
Eric Putnam db88cd9857
(PDOC-184) custom_type back to resource_type 2018-02-16 09:29:50 -08:00
Eric Putnam 176d6d4d8c
(PDOC-184) refactoring because naming is hard 2018-02-12 16:11:52 -08:00
Eric Putnam 8a34dc7ea4
rubocop sucks 2018-02-09 15:22:51 -08:00
Eric Putnam f6cd3ff4a8
(PDOC-184) implemented option and raises tags
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
2018-02-09 15:08:18 -08:00
Eric Putnam 56c24cc362
(PDOC-184) implement author tag
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
2018-02-08 12:12:56 -08:00
Eric Putnam 3635fe95f0
rubocop sucks 2018-02-07 15:24:48 -08:00
Eric Putnam 7c06ed77c4
(PDOC-184) block pointless output and re-add options
This makes sure the markdown doesn't include section headers that have no content. e.g. '## Classes' does not get put in if there are no classes. Also, we should deprecate --emit-json and --emit-json-stdout instead of just killing them.
2018-02-07 15:18:43 -08:00
Eric Putnam 1374b67da0
(PDOC-184) generate markdown
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
2018-02-07 14:04:19 -08:00
Eric Putnam 64d7b0e4db
(maint) add condition for misleading warning
There is a warning that displays when there is no text outside of tags for a given component, this text would become the 'Overview' section. The warning says: `[warn]: Missing documentation for Puppet class 'klass' at (stdin):4` The problem is that if the user has instead used the @summary tag, and is then using only tags, strings will report this warning even though there is clearly documentation. This adds a condition for the warning: If there is no text AND there are no tags, THEN output a warning saying there is no documentation.
2018-01-29 15:44:52 -08:00
David Schmitt 5156e8db10 (PDK-437) Add support for Resource API types 2018-01-29 16:17:30 +00:00
Antoine Musso fc2779202c Fix args handling for rake strings::generate
In the rake task strings::generate, the arguments json and yard_args
are not applied properly. The logic uses args.key?, however args is not
a Hash but a  Rake::TaskArguments (and Enumerable). There is now key?
method.

Use Rake::TaskArguments.has_key? instead.
2017-07-14 21:45:42 +02:00
Geoff Williams 203610d67c (PDOC-160) Remove the timestamp from output
Prevent mass-changes to files by removing the date in the footer of each page.
Since the generation date isn't particularly useful and isn't tied to either
a git revision or a released version, this could be an easy way to address this
bug.  The files will of-course be regenerated but if there are no changes then
the content will be identical and git will not notice.
2017-06-05 20:56:13 +10:00
Will Hopper 4990576f61 (PDOC-161) Add `summary` tag for short descriptions
This tag is primarily meant to be applied to Puppet classes,
but it is also supported by every other construct that can be
documented with strings.
2017-03-16 12:51:53 -07:00
Will Hopper 165170c08b (PDOC-155) Allow type documentation in Puppet 4 code
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.
2017-01-10 13:59:38 -08:00
Will Hopper 6ad74b0500 (PDOC-125) Display all puppet function signatures in top-level signature array
This commit adds a new top-level key to the JSON schema for Ruby 3x/4x
puppet functions: `signatures`. This key is an array and is constructed entirely
with data from existing elements of the puppet function object. The data
structure itself remains unchanged, as this commit only affects the final
JSON output for functions.

In the case of a puppet 4x function with multiple dispatches (overloads),
the signatures key is populated with the equivalent of an overload tag
for each which includes the signature and any param or return tags for
the dispatch.

In the case of a puppet function with only one dispatch, the array is
simply populated with a single element containing a lone dispatch
and its param and return tags.

Note that this change does not affect the internal structure or
representation of puppet function objects, but rather only affects
its final display form when serialized into JSON. All prior data
has been left intact, and the only change here is the addition
of the `signatures` member to the JSON output.
2016-11-14 12:53:49 -08:00
Will Hopper c56d9c60a4 (PDOC-129) Include tags in overload objects when serialized as JSON
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.
2016-11-14 11:45:45 -08:00
Jesse Scott df8e58b0c8 Merge pull request #125 from whopper/PDOC-135/4x_dispatch_return_type
(PDOC-135) Detect `return_type` calls in 4.x function dispatches
2016-11-14 11:37:05 -08:00
Jesse Scott bf68ae0022 Merge pull request #126 from whopper/PDOC-136/3x_function_return
(PDOC-136) Detect return type syntax in Puppet Language functions
2016-11-14 11:36:40 -08:00
Will Hopper 36bc0dd98c (PDOC-135) Detect `return_type` calls in 4.x function dispatches
Previously, Strings ignored calls to `return_type` in Puppet 4.x API
function dispatches, preventing the return types of overloads from
being automatically determined. This commit adds a check for a node
with a `return_type` call and handles it properly.
2016-11-14 11:04:41 -08:00
Will Hopper b3c8d52b25 (PDOC-136) Detect return type syntax in Puppet language functions
Previously, Strings ignored the return type in Puppet language functions
that used the following syntax:

function foo() >> String {}

This commit updates the FunctionStatement class to use the return
type from such a statement if it exists. In addition, Strings will
now emit a warning if the return type specified in the @return tag
doesn't match the type specified in the function definition.
2016-11-11 14:47:35 -08:00
Will Hopper 46af92731d (PDOC-93) Ensure search bar doesn't overlap item list in nav bar 2016-11-07 14:23:45 -08:00
Will Hopper 05806e7aee (PDOC-121) Include tag or SHA in gh_pages task commit
This commit updates the gh_pages task to reference the SHA
of the branch being documented in the documentation commit.

In addition, the description of each task except `update`
has been removed, as they are not useful on their own and
should be considered private. This is necessary in order
to hide the tasks from the output of `rake -T`.
2016-11-03 13:41:20 -07:00
Will Hopper e291f8cfe9 (PDOC-126) Remove `%Q` ruby quotation syntax from parsed strings
Previously, YARD would parse ruby strings which used %Q notation
and return the syntax literally. This commit adds a new Util
module with a `scrub_string` method to check for such a string
and remove the errant %Q and %q's.
2016-10-28 11:54:34 -07:00
Will Hopper 6e3c973868 (PDOC-120) Update gh_pages task to allow publishing of _index.html
Previously, due to Jekyll's default rule of not allowing files beginning
with an '_' to be published, the gh_pages rake task led to broken links.
This commit adds a step to the task which adds a _config.yml file to the
`doc` directory of the gh-pages branch which explicitly allows the file
to be published.
2016-10-13 12:12:13 -07:00