cloudformation-cli icon indicating copy to clipboard operation
cloudformation-cli copied to clipboard

Documentation generation broken for property pattern?

Open glb opened this issue 2 years ago • 1 comments

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 avatar Apr 05 '23 17:04 glb

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>

glb avatar May 31 '23 16:05 glb