(#300) Fix anchor links in Markdown docs

[danielparks]

Previously, anchors in generated Markdown were not unique. There were two problems:

1. Each parameter in a class, type, function, etc. had its own anchor, but the name of the anchor was just the normalized name of the parameter. This meant that all parameters with the same name would have the same anchor.

2. Classes, types, etc. had their ::s removed, whiched opened the (rare) possibility of having non-unique anchor names for unique type names.

This fixes those problems by:

1. Using the full name of the parameter, e.g. $my::class::param, to generate an anchor name.

2. Using a better anchor normalization routine. Each invalid character, i.e. not [a-zA-Z0-9_-], is converted to -. This should always result in unique anchor names for standard Puppet identifiers, since the only invalid characters sequences are :: and $ (which only appears once at the beginning of the string). Furthermore, - never appears in a valid Puppet identifier, so those two cases are the only way for it to be generated.

[CLAassistant]

All committers have signed the CLA.

[danielparks]

I was unable to run the acceptance tests:

❯ bundle exec rake 'litmus:provision[docker, centos:7]'
Cloning into 'spec/fixtures/modules/facts'...
Cloning into 'spec/fixtures/modules/provision'...
Cloning into 'spec/fixtures/modules/puppet_agent'...
fatal: unable to connect to github.com:
github.com[0: 140.82.113.4]: errno=Operation timed out

fatal: unable to connect to github.com:
github.com[0: 140.82.113.4]: errno=Operation timed out

fatal: unable to connect to github.com:
github.com[0: 140.82.113.4]: errno=Operation timed out

#<Thread:0x00000001072f03e8 /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/logging-2.3.1/lib/logging/diagnostic_context.rb:471 run> terminated with exception (report_on_exception is true):
/Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:196:in `clone_repo': Failed to clone git repository git://github.com/puppetlabs/puppetlabs-puppet_agent.git into spec/fixtures/modules/puppet_agent (RuntimeError)
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:364:in `download_repository'
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:427:in `block (2 levels) in <top (required)>'
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:315:in `block (2 levels) in download_items'
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/logging-2.3.1/lib/logging/diagnostic_context.rb:474:in `block in create_with_logging_context'
#<Thread:0x00000001072f08c0 /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/logging-2.3.1/lib/logging/diagnostic_context.rb:471 run> terminated with exception (report_on_exception is true):
/Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:196:in `clone_repo': Failed to clone git repository git://github.com/puppetlabs/provision.git into spec/fixtures/modules/provision (RuntimeError)
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:364:in `download_repository'
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:427:in `block (2 levels) in <top (required)>'
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:315:in `block (2 levels) in download_items'
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/logging-2.3.1/lib/logging/diagnostic_context.rb:474:in `block in create_with_logging_context'
#<Thread:0x00000001072f0f78 /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/logging-2.3.1/lib/logging/diagnostic_context.rb:471 run> terminated with exception (report_on_exception is true):
/Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:196:in `clone_repo': Failed to clone git repository git://github.com/puppetlabs/puppetlabs-facts.git into spec/fixtures/modules/facts (RuntimeError)
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:364:in `download_repository'
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:427:in `block (2 levels) in <top (required)>'
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:315:in `block (2 levels) in download_items'
    from /Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/logging-2.3.1/lib/logging/diagnostic_context.rb:474:in `block in create_with_logging_context'
rake aborted!
Failed to clone git repository git://github.com/puppetlabs/puppetlabs-facts.git into spec/fixtures/modules/facts
/Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:196:in `clone_repo'
/Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:364:in `download_repository'
/Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:427:in `block (2 levels) in <top (required)>'
/Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/puppetlabs_spec_helper-4.0.1/lib/puppetlabs_spec_helper/tasks/fixtures.rb:315:in `block (2 levels) in download_items'
/Users/daniel/personal/projects/third-party/puppet-strings/.bundle/gems/ruby/3.1.0/gems/logging-2.3.1/lib/logging/diagnostic_context.rb:474:in `block in create_with_logging_context'
Tasks: TOP => spec_prep
(See full trace by running task with --trace)

I can access GitHub fine; so maybe it’s a Docker problem? I pretty much don’t use docker, so I have no idea.

[chelnak]

This looks fine to me. Thank you for providing such a clear description/commit message.