Support languages other than puppet within @example blocks

[traylenator]

Use Case

Be able to provide examples in other languages in particular YAML.
Currently all @example blocks are assumed to be puppet language.

Describe the Solution You Would Like

Don't really know yardoc so guessing what a syntax might be

@example(yaml) Specify a Yum repo
---
yum::repos:
    base:
        baseurl: 'https://repos.example.com/CentOS/base/'
        mirrorlist: '--'

A clear and concise description of what you want to happen.

Should be rendered as the following with pretty yaml.

# Example - Specify a yumrepo
---
yum::repos:
    base:
        baseurl: 'https://repos.example.com/CentOS/base/'
        mirrorlist: '--'

Describe Alternatives You've Considered

Folk have tried nesting a yaml code block but it turns weird.
(have used ' rather than ``` for the inner code block)

@example an example
'''yaml
---
foo:bar
'''

however this results in nonsense output.

Additional Context

Stems on from this merge request to clean up some previous attempts to render yaml.

voxpupuli/puppet-yum#171

which resulted a completely broken markdown result.

[greatflyingsteve]

Seconding this. Puppet DSL examples are great, but sometimes you need to show your users documentation for how their data needs to look in Hiera, or how to use a DSL function embedded in an EPP template. There needs to be a way to do this, or if a way already exists, then it needs to be documented somewhere.