feat(core): Adding examples docs, mainly policy commands

[elizabethhealy]

Mainly for docs.opentdf.io

[jakedoublev]

If you run one of the commands with -h in a smaller terminal window, how does the markdown render output appear? Could you please attach screenshots with different terminal sizes for reference in the PR?

[jrschumacher]

@elizabethhealy I think Jake brings up some good points. Could we add this output to another header which we can exclude from the CLI output? I'm open to suggestions that would allow this to be uniform. We use this function to style the docs which would allow you to strip any sections that should be omitted from the CLI docs.

I believe when I added example I didn't give an example of the output: https://github.com/opentdf/otdfctl/blob/main/docs/man/auth/client-credentials.md#examples

Finally, I think we need to cement the CLI that we are modeling our docs after, but when I've been doing it I tend to use man git, man ssh, and man openssl.

[elizabethhealy]

@elizabethhealy I think Jake brings up some good points. Could we add this output to another header which we can exclude from the CLI output? I'm open to suggestions that would allow this to be uniform. We use this function to style the docs which would allow you to strip any sections that should be omitted from the CLI docs.

I believe when I added example I didn't give an example of the output: https://github.com/opentdf/otdfctl/blob/main/docs/man/auth/client-credentials.md#examples

Finally, I think we need to cement the CLI that we are modeling our docs after, but when I've been doing it I tend to use man git, man ssh, and man openssl.

@jrschumacher i like this idea, is there a way to pick which headers are displayed in the help output? ideally i think id like both the input and output in whats displayed on the docs website but only the input on the help command

[jrschumacher]

@elizabethhealy yep in the styledoc function you should be able to iterate. We will need to add https://github.com/yuin/goldmark to parse the markdown and strip out the headers we don't want. Whether you strip before styling is up to you, but we do include https://github.com/charmbracelet/glamour for styling the markdown which also uses goldmark.

If you could just add a README to the man directory so we can keep track of the special headers or header tags.

Lastly in opentdf/docs there is a custom react component used to render the markdown into HTML. Inn that you can iterate and add or remove new elements.

[jakedoublev]

This is great! Looks like there are still example outputs for KAS grants and SCS creation, but this should be good to go after those are removed. 🎉

[elizabethhealy]

@jakedoublev thanks good catch! should be ready now.
i played around with goldmark a bit but just removed the output for the short term, figured i can come back to it on engineering day since its just a nice to have