Add Puppet Data Type documentation

[glennsarti]

Builds on #205

WIP do not merge

Addresses PDOC-226.
Also fixes PDOC- 215, 73

• Acceptance Tests (Pending (maint) Use Litmus for acceptance testing. #204)

• Address all TODOs

• Ruby Data types e.g. https://github.com/puppetlabs/puppet/blob/ba4d1a1aba0095d3c70b98fea5c67434a4876a61/lib/puppet/datatypes.rb#L15-L22

• Puppet Data types e.g. https://github.com/puppetlabs/puppet/blob/ba4d1a1aba0095d3c70b98fea5c67434a4876a61/lib/puppet/datatypes.rb#L28-L32

• Puppet Data type aliases e.g. https://puppet.com/docs/puppet/5.3/lang_type_aliases.html

• JSON Renderer

• HTML Renderer

• Markdown Renderer

• Tests - Ruby DataType handler

• Tests - Puppet Data Type handler

• Tests - JSON Renderer for all data types

• Tests - HTML Renderer for all data types

• Tests - Markdown Renderer for all data types

Punting

• Local Data types e.g. https://github.com/puppetlabs/puppet/blob/master/lib/puppet/functions/lookup.rb#L127-L147 Punting... Too hard.

• What about functions in a Type? e.g. https://github.com/puppetlabs/bolt/blob/f8ca10a77aa3e6eb44f098add3d08da55b122b98/bolt-modules/boltlib/lib/puppet/datatypes/resultset.rb
  Punting for now.

[glennsarti]

Markdown rendering is basically done.

For both full ruby data types and puppet type aliases

EDIT: removed picture as it's no longer relevant

[scotje]

Noticed a couple minor things.

I don't really feel qualified to review all the parser machinations though, maybe @kris-bosland could weigh in on some of that?

[glennsarti]

Example Output

Given the following files

# An example Puppet Data Type in Ruby.
#
# @param arg1 [String[1]] A message parameter.
# @param arg2 Optional String parameter. Defaults to 'param'.
# @param badarg3 Optional String parameter. Defaults to 'param'.
Puppet::DataTypes.create_type('RubyDataType') do
  interface <<-PUPPET
    attributes => {
      arg1   => Numeric,
      missingarg1   => { type => OString[1], value => "missing" },
      arg2  => { type => Optional[String[1]], value => "param" }
    }
    PUPPET
end

and

# Documentation for Defaultmodule Modultetypealias
type Defaultmodule::Modultetypealias = Pattern[/^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])$/]

Outputs

JSON

...
  "data_types": [
    {
      "name": "RubyDataType",
      "file": "C:/Source/puppet-editor-services/spec/languageserver-sidecar/fixtures/real_agent/cache/lib/puppet/datatypes/cachedatatype.rb",
      "line": 6,
      "docstring": {
        "text": "An example Puppet Data Type in Ruby.",
        "tags": [
          {
            "tag_name": "param",
            "text": "A message parameter.",
            "types": [
              "Numeric"
            ],
            "name": "arg1"
          },
          {
            "tag_name": "param",
            "text": "Optional String parameter. Defaults to 'param'.",
            "types": [
              "Optional[String[1]]"
            ],
            "name": "arg2"
          },
          {
            "tag_name": "param",
            "text": "",
            "types": [
              "OString[1]"
            ],
            "name": "missingarg1"
          }
        ]
      },
      "defaults": {
        "missingarg1": "missing",
        "arg2": "param"
      },
      "source": null
    }
  ],
  "data_type_aliases": [
    {
      "name": "Defaultmodule::Modultetypealias",
      "file": "C:/Source/puppet-editor-services/spec/languageserver-sidecar/fixtures/real_agent/environments/testfixtures/modules/defaultmodule/types/moduletypealias.pp",
      "line": 2,
      "docstring": {
        "text": "Documentation for Defaultmodule Modultetypealias"
      },
      "alias_of": "Pattern[/^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\-]*[a-zA-Z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\\-]*[A-Za-z0-9])$/]"
    }
  ],
...

Markdown

---

Reference

Table of Contents

...

Data types

• Defaultmodule::Modultetypealias: Documentation for Defaultmodule Modultetypealias
• RubyDataType: An example Puppet Data Type in Ruby.

---

Data types

Defaultmodule::Modultetypealias

Documentation for Defaultmodule Modultetypealias

Alias of Pattern[/^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])$/]

RubyDataType

An example Puppet Data Type in Ruby.

Parameters

The following parameters are available in the RubyDataType data type.

arg1

Data type: Numeric

A message parameter.

arg2

Data type: Optional[String[1]]

Optional String parameter. Defaults to 'param'.

Default value: param

missingarg1

Data type: OString[1]

Default value: missing

---

HTML

Index

Type Alias

Type Alias

[glennsarti]

@jbondpdx Updated with images of outputs.

[jbondpdx]

@glennsarti the regex pattern looks a little overwhelming and a bit incomprehensible to me. The caveat is that I don't know regex (I know, it's on the list of "things to learn"), so maybe most people will see that and easily read/understand it? I'll defer to you and the other devs on that one.

[glennsarti]

@jbondpdx The regex was just an example of what the documentation will look like for a given source file. Also it's quite long so seeing how things wrap text or would using ellipsis (...) be appropriate etc.

This example is from stdlib - https://github.com/puppetlabs/puppetlabs-stdlib/blob/822c4d2c85a838c8bcfea48efcf399fbeb719a59/types/fqdn.pp#L1

[jbondpdx]

Fair enough, Glenn!

…

On Mon, Jul 1, 2019 at 4:48 PM Glenn Sarti ***@***.***> wrote: @jbondpdx <https://github.com/jbondpdx> The regex was just an example of what the documentation will look like for a given source file. Also it's quite long so seeing how things wrap text or would using ellipsis (...) be appropriate etc. This example is from stdlib - https://github.com/puppetlabs/puppetlabs-stdlib/blob/822c4d2c85a838c8bcfea48efcf399fbeb719a59/types/fqdn.pp#L1 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#199?email_source=notifications&email_token=AB4PMACV3NSF6VORPL42VGLP5KJVJA5CNFSM4HYUOVT2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODY7UZII#issuecomment-507464865>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AB4PMAGHJS4T2V6ITVLOHSLP5KJVJANCNFSM4HYUOVTQ> .

-- Jean Bond Senior Technical Writer Puppet

[scotje]

This PR looks good but it looks like you wanted to add some acceptance tests once #204 was merged which I just did. :)

[glennsarti]

@scotje Correct! and now that 204 is merged I can move forward with that

[trevor-vaughan]

Just tried this for generating my REFERENCE.md and it appears to work great.

[glennsarti]

Acceptance tests added and green.

[scotje]

🎉

[alexjfisher]

I've left feedback on the puppet-strings styleguide page, as it explicitly states type aliases are not supported.

[alexjfisher]

Works great BTW! Thanks! :)