puppet-strings 2.9.0 → 3.0.1

data/README.md

@@ -1,24 +1,16 @@
-Puppet Strings
-==============
-[![Build Status](https://travis-ci.org/puppetlabs/puppet-strings.png?branch=main)](https://travis-ci.org/puppetlabs/puppet-strings) [![Gem Version](https://badge.fury.io/rb/puppet-strings.svg)](https://badge.fury.io/rb/puppet-strings)
+# Puppet strings
 
-Puppet Strings generates documentation for Puppet code and extensions written in Puppet and Ruby. Strings processes code and YARD-style code comments to create documentation in HTML, Markdown, or JSON formats.
+[![ci](https://github.com/puppetlabs/puppet-strings/actions/workflows/ci.yml/badge.svg)](https://github.com/puppetlabs/puppet-strings/actions/workflows/ci.yml) [![Gem Version](https://badge.fury.io/rb/puppet-strings.svg)](https://badge.fury.io/rb/puppet-strings)
 
-
-|                |                                                                 |
-| -------------- |---------------------------------------------------------------- |
-| *Code*         | [GitHub][repo]                                                  |
-| *Issues*       | [GitHub issues][issues]                                         |
-| *License*      | [Apache 2.0][LICENSE]                                           |
-| *Change log*   | [CHANGELOG.md][changelog]                                       |
-| *Contributing* | [CONTRIBUTING.md][contributing] and [COMMITTERS.md][committers] |
+Puppet Strings generates documentation for Puppet code and extensions written in Puppet and Ruby.
+Strings processes code and YARD-style code comments to create documentation in HTML, Markdown, or JSON formats.
 
 ## Installing Puppet Strings
 
 ### Requirements
 
-  * Ruby 2.1.9 or newer
-  * Puppet 4.0.0 or newer
+* Ruby 2.7.0 or newer
+* Puppet 6.0.0 or newer
 
 ### Install Puppet Strings
 
@@ -28,7 +20,7 @@ Installation instructions vary slightly depending on how you have installed Pupp
 
 Install the `puppet-strings` gem into the `puppet-agent` environment:
 
-```
+``` bash
 sudo /opt/puppetlabs/puppet/bin/gem install puppet-strings
 ```
 
@@ -36,35 +28,44 @@ sudo /opt/puppetlabs/puppet/bin/gem install puppet-strings
 
 Install the `puppet-strings` gem into the same Ruby installation where you have installed the `puppet` gem:
 
-```
+``` bash
 gem install puppet-strings
 ```
 
 ### Configure Puppet Strings (Optional)
 
- To use YARD options with Puppet Strings, specify a `.yardopts` file in the same directory in which you run `puppet strings`. Puppet Strings supports the Markdown format and automatically sets the YARD `markup` option to `markdown`.
+To use YARD options with Puppet Strings, specify a `.yardopts` file in the same directory in which you run `puppet strings`.
+
+Puppet Strings supports the Markdown format and automatically sets the YARD `markup` option to `markdown`.
+
+To see a list of available YARD options, run `yard help doc`.
 
- To see a list of available YARD options, run `yard help doc`. For details about YARD options configuration, see the [YARD docs](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#config).
+For details about YARD options configuration, see the [YARD docs](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#config).
 
 ## Generating documentation with Puppet Strings
 
 By default, Puppet Strings outputs documentation as HTML, or you can specify JSON or Markdown output instead.
 
-Strings generates reference documentation based on the code and Strings code comments in all Puppet and Ruby source files under the `./manifests/`, `./functions/`, `./lib/`, `./types/`, and `./tasks/` directories.
+Strings generates reference documentation based on the code and Strings code comments in all Puppet and
+Ruby source files under the `./manifests/`, `./functions/`, `./lib/`, `./types/`, and `./tasks/` directories.
 
 Strings outputs HTML of the reference information and the module README to the module's `./doc/` directory. This output can be rendered in any browser.
 
-JSON and Markdown output include the reference documentation only. Strings sends JSON output to either STDOUT or to a file. Markdown output is written to a REFERENCE.md file in the module's main directory.
+JSON and Markdown output include the reference documentation only.
+Strings sends JSON output to either STDOUT or to a file.
+Markdown output is written to a REFERENCE.md file in the module's main directory.
 
-See the [Puppet Strings documentation](https://puppet.com/docs/puppet/latest/puppet_strings.html) for complete instructions for generating documentation with Strings. For code comment style guidelines and examples, see the [Puppet Strings style guide](https://puppet.com/docs/puppet/5.5/puppet_strings_style.html).
+See the [Puppet Strings documentation](https://puppet.com/docs/puppet/latest/puppet_strings.html) for complete instructions for generating documentation with Strings.
+
+For code comment style guidelines and examples, see the [Puppet Strings style guide](https://puppet.com/docs/puppet/latest/puppet_strings_style.html).
 
 ### Additional Resources
 
 Here are a few other good resources for getting started with documentation:
 
-  * [Module README Template](https://puppet.com/docs/puppet/latest/puppet_strings.html)
-  * [YARD Getting Started Guide](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md)
-  * [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md)
+* [Module README Template](https://puppet.com/docs/puppet/latest/puppet_strings.html)
+* [YARD Getting Started Guide](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md)
+* [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md)
 
 ## Developing and Contributing
 
@@ -78,72 +79,58 @@ If you plan on developing features or fixing bugs in Puppet Strings, it is essen
 
 To run specs, run the `spec` rake task:
 
-    $ bundle install --path .bundle/gems
-    $ bundle exec rake spec
+``` bash
+bundle install --path .bundle/gems
+bundle exec rake spec
+```
 
 ### Running Acceptance Tests
 
-We are experimenting with a new tool for running acceptance tests. It's name is [puppet_litmus](https://github.com/puppetlabs/puppet_litmus) and replaces beaker as the test runner.
+Acceptance tests can be executed with [puppet_litmus](https://github.com/puppetlabs/puppet_litmus).
 
 An example of running the acceptance tests locally with Docker:
 
 1. Ensure [Docker](https://www.docker.com/products/docker-desktop) is installed and running.
 
-2. Install Ruby gems. This step can be skipped if you have already followed the [Running Specs](#running-specs) instructions
+2. Install Ruby gems. This step can be skipped if you have already followed the [Running Specs](#running-specs) instructions.
 
-``` text
-    $ bundle install --path .bundle/gems
-```
+    ``` bash
+    bundle install --path .bundle/gems
+    ```
 
 3. Provision a docker container, in this case CentOS 7
 
-``` text
-    $ bundle exec rake 'litmus:provision[docker, centos:7]'
-```
+    ``` bash
+    bundle exec rake 'litmus:provision[docker, centos:7]'
+    ```
 
 4. Install test items; Puppet Agent, our test module, and the puppet-strings gem built from this source code
 
-``` text
-    $ bundle exec rake 'litmus:install_agent[puppet6]'
-    $ bundle exec rake 'litmus:install_modules_from_directory[./spec/fixtures/acceptance/modules]'
-    $ bundle exec rake litmus:install_gems
-```
+    ``` bash
+    bundle exec rake 'litmus:install_agent[puppet6]'
+    bundle exec rake 'litmus:install_modules_from_directory[./spec/fixtures/acceptance/modules]'
+    bundle exec rake litmus:install_gems
+    ```
 
 5. Run the acceptance tests. These tests can be run more than once without the need to run the provisioning steps again
 
-``` text
-    $ bundle exec rake litmus:acceptance:parallel
-```
+    ``` bash
+    bundle exec rake litmus:acceptance:parallel
+    ```
 
 6. Remove any test containers
 
-``` text
-    $ bundle exec rake litmus:tear_down
-```
-
-The [Litmus Wiki](https://github.com/puppetlabs/puppet_litmus/wiki) contains more indepth information about Litmus. There is also a tutorial on using Litmus with an example [Puppet Module](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module)
-
-
-An example of run the acceptance tests follow the instructions [here].
+    ``` bash
+    bundle exec rake litmus:tear_down
+    ```
 
 ## Support
 
-Please log issues in [GitHub issues][issues]. Check out [CONTRIBUTING.md][contributing] for tips on writing _the best_ issues.
+Please log issues in [GitHub issues](https://github.com/puppetlabs/puppet-strings/issues).
+Check out [CONTRIBUTING.md](https://github.com/puppetlabs/puppet-strings/blob/main/CONTRIBUTING.md) for tips on writing _the best_ issues.
 
-A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is available for asking questions and getting help from others.
-
-There is also an active community on the [Puppet community Slack][] in the #forge-modules channel.
+There is also an active community on the [Puppet community Slack](https://slack.puppet.com) in the #forge-modules channel.
 
 We use semantic version numbers for our releases and recommend that users upgrade to patch releases and minor releases as they become available.
 
-Bug fixes and ongoing development will occur in minor releases for the current major version. Security fixes will be ported to a previous major version on a best-effort basis, until the previous major version is no longer maintained.
-
-
-[repo]: https://github.com/puppetlabs/puppet-strings
-[issues]: https://github.com/puppetlabs/puppet-strings/issues
-[LICENSE]: https://github.com/puppetlabs/puppet-strings/blob/main/LICENSE
-[changelog]: https://github.com/puppetlabs/puppet-strings/blob/main/CHANGELOG.md
-[contributing]: https://github.com/puppetlabs/puppet-strings/blob/main/CONTRIBUTING.md
-[committers]: https://github.com/puppetlabs/puppet-strings/blob/main/COMMITTERS.md
-[Puppet community Slack]: https://slack.puppet.com
-
+Bug fixes and ongoing development will occur in minor releases for the current major version.

data/lib/puppet/face/strings.rb

@@ -18,12 +18,6 @@ Puppet::Face.define(:strings, '0.0.1') do
     option '--markup FORMAT' do
       summary "The markup format to use for docstring text (defaults to 'markdown')."
     end
-    option '--emit-json-stdout' do
-      summary 'DEPRECATED: Print JSON representation of the documentation to stdout.'
-    end
-    option '--emit-json PATH' do
-      summary 'DEPRECATED: Write JSON representation of the documentation to the given file.'
-    end
 
     summary 'Generate documentation from files.'
     arguments '[[search_pattern] ...]'
@@ -32,9 +26,9 @@ Puppet::Face.define(:strings, '0.0.1') do
       check_required_features
       require 'puppet-strings'
 
-      PuppetStrings::generate(
+      PuppetStrings.generate(
         args.count > 1 ? args[0..-2] : PuppetStrings::DEFAULT_SEARCH_PATTERNS,
-        build_generate_options(args.last)
+        build_generate_options(args.last),
       )
       nil
     end
@@ -79,35 +73,34 @@ Puppet::Face.define(:strings, '0.0.1') do
         return
       end
       puts 'Starting YARD documentation server.'
-      PuppetStrings::run_server('-m', *module_docs)
+      PuppetStrings.run_server('-m', *module_docs)
       nil
     end
   end
 
-  action(:describe) do #This is Kris' experiment with string based describe
-    option "--list" do
-      summary "list types"
+  action(:describe) do # This is Kris' experiment with string based describe
+    option '--list' do
+      summary 'list types'
     end
-    option "--providers" do
-      summary "provide details on providers"
+    option '--providers' do
+      summary 'provide details on providers'
     end
 
-#TODO: Implement the rest of describe behavior
-#     * --help:
-#   Print this help text
+    # TODO: Implement the rest of describe behavior
+    #     * --help:
+    #   Print this help text
 
-# * --providers:
-#   Describe providers in detail for each type
+    # * --providers:
+    #   Describe providers in detail for each type
 
-# * --list:
-#   List all types
+    # * --list:
+    #   List all types
 
-# * --meta:
-#   List all metaparameters
-
-# * --short:
-#   List only parameters without detail
+    # * --meta:
+    #   List all metaparameters
 
+    # * --short:
+    #   List only parameters without detail
 
     when_invoked do |*args|
       check_required_features
@@ -117,27 +110,24 @@ Puppet::Face.define(:strings, '0.0.1') do
       options[:describe] = true
       options[:stdout] = true
       options[:format] = 'json'
-      
+
       if args.length > 1
         if options[:list]
-          warn "WARNING: ignoring types when listing all types."
+          warn 'WARNING: ignoring types when listing all types.'
         else
           options[:describe_types] = args[0..-2]
         end
       end
 
-      #TODO: Set up search_patterns and whatever else needed to collect data for describe - currently missing some
+      # TODO: Set up search_patterns and whatever else needed to collect data for describe - currently missing some
       #          manifests/**/*.pp
       #          functions/**/*.pp
       #          tasks/*.json
       #          plans/*.pp
-      search_patterns = %w(
-        types/**/*.pp
-        lib/**/*.rb
-      )
-      PuppetStrings::generate(
+      search_patterns = ['types/**/*.pp', 'lib/**/*.rb']
+      PuppetStrings.generate(
         search_patterns,
-        build_generate_options(options)
+        build_generate_options(options),
       )
       nil
     end
@@ -146,9 +136,9 @@ Puppet::Face.define(:strings, '0.0.1') do
   # Checks that the required features are installed.
   # @return [void]
   def check_required_features
-    raise RuntimeError, "The 'yard' gem must be installed in order to use this face." unless Puppet.features.yard?
-    raise RuntimeError, "The 'rgen' gem must be installed in order to use this face." unless Puppet.features.rgen?
-    raise RuntimeError, 'This face requires Ruby 1.9 or greater.' if RUBY_VERSION.match?(/^1\.8/)
+    raise "The 'yard' gem must be installed in order to use this face." unless Puppet.features.yard?
+    raise "The 'rgen' gem must be installed in order to use this face." unless Puppet.features.rgen?
+    raise 'This face requires Ruby 1.9 or greater.' if RUBY_VERSION.match?(%r{^1\.8})
   end
 
   # Builds the options to PuppetStrings.generate.
@@ -161,12 +151,6 @@ Puppet::Face.define(:strings, '0.0.1') do
     generate_options[:backtrace] = Puppet[:trace]
     generate_options[:yard_args] = yard_args unless yard_args.empty?
     if options
-      if options[:emit_json]
-        warn "WARNING: '--emit-json PATH' is deprecated. Use '--format json --out PATH' instead."
-      end
-      if options[:emit_json_stdout]
-        warn "WARNING: '--emit-json-stdout' is deprecated. Use '--format json' instead."
-      end
       markup = options[:markup]
       generate_options[:markup] = markup if markup
       generate_options[:path] = options[:out] if options[:out]
@@ -182,15 +166,11 @@ Puppet::Face.define(:strings, '0.0.1') do
       if format
         if format.casecmp('markdown').zero?
           generate_options[:markdown] = true
-        elsif format.casecmp('json').zero? || options[:emit_json] || options[:emit_json_stdout]
+        elsif format.casecmp('json').zero?
           generate_options[:json] = true
-          generate_options[:path] ||= options[:emit_json] if options[:emit_json]
         else
-          raise RuntimeError, "Invalid format #{options[:format]}. Please select 'json' or 'markdown'."
+          raise "Invalid format #{options[:format]}. Please select 'json' or 'markdown'."
         end
-      elsif options[:emit_json] || options[:emit_json_stdout]
-        generate_options[:json] = true
-        generate_options[:path] ||= options[:emit_json] if options[:emit_json]
       end
     end
     generate_options

data/lib/puppet/feature/rgen.rb

@@ -2,4 +2,4 @@
 
 require 'puppet/util/feature'
 
-Puppet.features.add(:rgen, :libs => ['rgen/metamodel_builder', 'rgen/ecore/ecore'])
+Puppet.features.add(:rgen, libs: ['rgen/metamodel_builder', 'rgen/ecore/ecore'])

data/lib/puppet/feature/yard.rb

@@ -2,4 +2,4 @@
 
 require 'puppet/util/feature'
 
-Puppet.features.add(:yard, :libs => ['yard'])
+Puppet.features.add(:yard, libs: ['yard'])

data/lib/puppet-strings/describe.rb

@@ -8,16 +8,16 @@ module PuppetStrings::Describe
   # Renders requested types or a summarized list in the current YARD registry to STDOUT.
   # @param [Array] describe_types The list of names of the types to be displayed.
   # @param [bool] list Create the summarized list instead of describing each type.
-  # @param [bool] providers Show details of the providers.
+  # @param [bool] _providers Show details of the providers.
   # @return [void]
-  def self.render(describe_types = [], list = false, providers = false)
+  def self.render(describe_types = [], list = false, _providers = false)
     document = {
       defined_types: YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash),
-      resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash),        
+      resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash),
     }
 
     if list
-      puts "These are the types known to puppet:"
+      puts 'These are the types known to puppet:'
       document[:resource_types].each { |t| list_one_type(t) }
     else
       document[:providers] = YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash)
@@ -26,31 +26,31 @@ module PuppetStrings::Describe
       describe_types.each { |name| type_names[name] = true }
 
       document[:resource_types].each do |t|
-        show_one_type(t, providers) if type_names[t[:name].to_s]
+        show_one_type(t) if type_names[t[:name].to_s]
       end
     end
   end
 
-  def self.show_one_type(resource_type, providers = false)
-    puts "\n%{name}\n%{underscore}" % { name: resource_type[:name], underscore: "=" * resource_type[:name].length }
+  def self.show_one_type(resource_type)
+    puts "\n%{name}\n%{underscore}" % { name: resource_type[:name], underscore: '=' * resource_type[:name].length }
     puts resource_type[:docstring][:text]
 
     combined_list = (resource_type[:parameters].nil? ? [] : resource_type[:parameters]) +
                     (resource_type[:properties].nil? ? [] : resource_type[:properties])
 
-    if combined_list.any?
-      puts "\nParameters\n----------"
-      combined_list.sort_by { |p| p[:name] }.each { |p| show_one_parameter(p) }
-      puts "\nProviders\n---------"
-    end
-    #Show providers here - list or provide details      
+    return unless combined_list.any?
+
+    puts "\nParameters\n----------"
+    combined_list.sort_by { |p| p[:name] }.each { |p| show_one_parameter(p) }
+    puts "\nProviders\n---------"
+    # Show providers here - list or provide details
   end
 
   def self.show_one_parameter(parameter)
     puts "\n- **%{name}**\n" % { name: parameter[:name] }
     puts parameter[:description]
-    puts "Valid values are `%{values}`." % { values: parameter[:values].join("`, `") } unless parameter[:values].nil?
-    puts "Requires features %{required_features}." % { required_features: parameter[:required_features] } unless parameter[:required_features].nil?
+    puts 'Valid values are `%{values}`.' % { values: parameter[:values].join('`, `') } unless parameter[:values].nil?
+    puts 'Requires features %{required_features}.' % { required_features: parameter[:required_features] } unless parameter[:required_features].nil?
   end
 
   def self.list_one_type(type)
@@ -58,13 +58,13 @@ module PuppetStrings::Describe
     shortento = targetlength - 4
     contentstring = type[:docstring][:text]
     end_of_line = contentstring.index("\n")  # "." gives closer results to old describeb, but breaks for '.k5login'
-    if !end_of_line.nil?
+    unless end_of_line.nil?
       contentstring = contentstring[0..end_of_line]
     end
     if contentstring.length > targetlength
       contentstring = contentstring[0..shortento] + ' ...'
     end
-    
-    puts "%-15s - %-s" % [type[:name], contentstring]
+
+    puts "#{type[:name].to_s.ljust(15)} - #{contentstring}"
   end
 end

data/lib/puppet-strings/markdown/base.rb

@@ -3,12 +3,14 @@
 require 'puppet-strings'
 require 'puppet-strings/json'
 require 'puppet-strings/yard'
+require 'puppet-strings/markdown/helpers'
 
+# Implements classes that make elements in a YARD::Registry hash easily accessible for template.
 module PuppetStrings::Markdown
   # This class makes elements in a YARD::Registry hash easily accessible for templates.
   #
   # Here's an example hash:
-  #{:name=>:klass,
+  # {:name=>:klass,
   # :file=>"(stdin)",
   # :line=>16,
   # :inherits=>"foo::bar",
@@ -49,6 +51,36 @@ module PuppetStrings::Markdown
   #  ") inherits foo::bar {\n" +
   #  "}"}
   class Base
+    # Helpers for ERB templates
+    include PuppetStrings::Markdown::Helpers
+
+    # Set or return the name of the group
+    #
+    # @param [Optional[String]] Name of the group to set
+    # @return [String] Name of the group
+    def self.group_name(name = nil)
+      @group_name = name if name
+      @group_name
+    end
+
+    # Set or return the types registered with YARD
+    #
+    # @param [Optional[Array[Symbol]]] Array of symbols registered with YARD to set
+    # @return [Array[Symbol]] Array of symbols registered with YARD
+    def self.yard_types(types = nil)
+      @yard_types = types if types
+      @yard_types
+    end
+
+    # @return [Array] list of items
+    def self.items
+      yard_types
+        .flat_map { |type| YARD::Registry.all(type) }
+        .sort_by(&:name)
+        .map(&:to_hash)
+        .map { |i| new(i) }
+    end
+
     def initialize(registry, component_type)
       @type = component_type
       @registry = registry
@@ -57,11 +89,11 @@ module PuppetStrings::Markdown
 
     # generate 1:1 tag methods
     # e.g. {:tag_name=>"author", :text=>"eputnam"}
-    { :return_val => 'return',
-      :since => 'since',
-      :summary => 'summary',
-      :note => 'note',
-      :todo => 'todo' }.each do |method_name, tag_name|
+    { return_val: 'return',
+      since: 'since',
+      summary: 'summary',
+      note: 'note',
+      todo: 'todo' }.each do |method_name, tag_name|
       # @return [String] unless the tag is nil or the string.empty?
       define_method method_name do
         @tags.find { |tag| tag[:tag_name] == tag_name && !tag[:text].empty? }[:text] if @tags.any? { |tag| tag[:tag_name] == tag_name && !tag[:text].empty? }
@@ -95,7 +127,11 @@ module PuppetStrings::Markdown
 
     # @return [Array] parameter tag hashes
     def params
-      select_tags('param')
+      tags = @tags.select { |tag| tag[:tag_name] == 'param' }.map do |param|
+        param[:link] = clean_link("$#{name}::#{param[:name]}")
+        param
+      end
+      tags.empty? ? nil : tags
     end
 
     # @return [Array] example tag hashes
@@ -144,27 +180,14 @@ module PuppetStrings::Markdown
       {
         name: name.to_s,
         link: link,
-        desc: summary || @registry[:docstring][:text][0..140].gsub("\n",' '),
+        desc: summary || @registry[:docstring][:text][0..140].tr("\n", ' '),
         private: private?
       }
     end
 
     # @return [String] makes the component name suitable for a GitHub markdown link
     def link
-      name.delete('::').strip.gsub(' ','-').downcase
-    end
-
-    # Some return, default, or valid values need to be in backticks. Instead of fu in the handler or code_object, this just does the change on the front.
-    # @param value
-    #  any string
-    # @return [String] value or value in backticks if it is in a list
-    def value_string(value)
-      to_symbol = %w[undef true false]
-      if to_symbol.include? value
-        return "`#{value}`"
-      else
-        return value
-      end
+      clean_link(name)
     end
 
     def private?
@@ -174,18 +197,18 @@ module PuppetStrings::Markdown
     def word_wrap(text, line_width: 120, break_sequence: "\n")
       return unless text
 
-      text.split("\n").collect! do |line|
-        line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1#{break_sequence}").strip : line
-      end * break_sequence
+      text.split("\n").map! { |line|
+        line.length > line_width ? line.gsub(%r{(.{1,#{line_width}})(\s+|$)}, "\\1#{break_sequence}").strip : line
+      } * break_sequence
     end
 
     # @return [String] full markdown rendering of a component
     def render(template)
+      file = File.join(File.dirname(__FILE__), 'templates', template)
       begin
-        file = File.join(File.dirname(__FILE__),"templates/#{template}")
-        ERB.new(File.read(file), nil, '-').result(binding)
+        PuppetStrings::Markdown.erb(file).result(binding)
       rescue StandardError => e
-        fail "Processing #{@registry[:file]}:#{@registry[:line]} with #{file} => #{e}"
+        raise "Processing #{@registry[:file]}:#{@registry[:line]} with #{file} => #{e}"
       end
     end
 
@@ -195,5 +218,17 @@ module PuppetStrings::Markdown
       tags = @tags.select { |tag| tag[:tag_name] == name }
       tags.empty? ? nil : tags
     end
+
+    # Convert an input into a string appropriate for an anchor name.
+    #
+    # This converts any character not suitable for an id attribute into a '-'. Generally we're running this on Puppet identifiers for types and
+    # variables, so we only need to worry about the special characters ':' and '$'. With namespaces Puppet variables this should always be produce a
+    # unique result from a unique input, since ':' only appears in pairs, '$' only appears at the beginning, and '-' never appears.
+    #
+    # @param [String] the input to convert
+    # @return [String] the anchor-safe string
+    def clean_link(input)
+      input.tr('^a-zA-Z0-9_-', '-')
+    end
   end
 end

data/lib/puppet-strings/markdown/data_type.rb

@@ -8,6 +8,9 @@ module PuppetStrings::Markdown
     attr_reader :alias_of
     attr_reader :functions
 
+    group_name 'Data types'
+    yard_types [:puppet_data_type, :puppet_data_type_alias]
+
     def initialize(registry)
       @template = 'data_type.erb'
       super(registry, 'data type')
@@ -20,6 +23,7 @@ module PuppetStrings::Markdown
     end
   end
 
+  # Generates Markdown for a Puppet Function.
   class DataType::Function < Base
     def initialize(registry)
       super(registry, 'data_type_function')

data/lib/puppet-strings/markdown/defined_type.rb

@@ -3,7 +3,11 @@
 require 'puppet-strings/markdown/base'
 
 module PuppetStrings::Markdown
+  # Generates Markdown for a Puppet Defined Type.
   class DefinedType < Base
+    group_name 'Defined types'
+    yard_types [:puppet_defined_type]
+
     def initialize(registry)
       @template = 'classes_and_defines.erb'
       super(registry, 'defined type')