aws-cloudformation / cloudformation-cli

The CloudFormation Provider Development Toolkit allows you to author your own resource providers and modules that can be used by CloudFormation.
Apache License 2.0
318 stars 161 forks source link

Documentation generation broken for property pattern? #983

Open glb opened 1 year ago

glb commented 1 year ago

The automatic docs generation is really great to have, thank you!

There does seem to be a small issue with patterns, though. I have a property in my type definition that looks like this:

    "Example": {
      "description": "An example description for this field.",
      "type": "string",
      "pattern": "^[a-zA-Z0-9]+$"
    }

which results in the following Markdown being generated:

_Pattern_: <code>^[a-zA-Z0-9]+$</code>

which is rendered like a footnote:

image

...

image

If the [ character is escaped, like this:

_Pattern_: <code>^\[a-zA-Z0-9]+$</code>

then the rendering is more like what I expected to see:

image

It is possible that there are other places that have similar issues; I have not done a deep dive trying to identify other cases.

I'm running version 0.2.28 which appears to be the latest available at the moment.

$ cfn-cli --version
cfn 0.2.28
glb commented 1 year ago

The following change to rpdk/core/templates/docs-readme.md appears to address the issue, not sure if there are better ways to do it or other things to worry about.

- _Pattern_: <code>{{ prop.pattern }}</code>
+ _Pattern_: <code>{{ prop.pattern | replace("[", "\\[") }}</code>