Generate CLI reference

[itowlson]

An experiment in support of spinframework/spin-docs#72

cc @kate-goldenring

e.g. spin maintenance generate-reference -o REFME.md

[kate-goldenring]

Thanks for looking into this @itowlson. Can you also commit the initial CLI.md?

[kate-goldenring]

Should we move the fork to spinframework's repo?

[itowlson]

I am not sure what to do with the fork. It can't live in my personal account I agree. But it feels awkward to have something so disconnected from Spin and so specifically about Clap in spinframework. Maybe that's just me. We could make it a crate in the Spin project, but then we would lose traceability to the original repo and author, which feels rude.

Anyway I'm happy to follow whatever you and other folks more steeped on open-source etiquette advise!

[kate-goldenring]

That is a good point. I think we can leave it as a fork on your account but can you add a comment as to why we have a fork and the condition of leaving the fork, which seems to be if/when we move to clap 3?

[itowlson]

@kate-goldenring I wasn't planning to commit the generated Markdown. I thought that was going to go to the docs site? I don't want to get into a position where anyone working on the CLI has to remember to regenerate the Markdown and commit the changes - I was more imagining this command running in CI as part of a release (and hopefully PRing to the docs repo so that all we need to do is mash the approve and merge button).

[itowlson]

I tweaked this so it defaults to writing to stdout. My thought is that we can have a GH workflow (or step in the release workflow) that does something like:

• cat the Bartholomew frontmatter of the CLI reference page to a file e.g. cli-reference.md
• spin maintenance generate-reference >>cli-reference.md
• PR cli-reference.md to the appropriate place in spin-docs

(We can't use MarkdownOptions::title() to set the front matter as it always prepends a # heading marker. Although I suppose I could change that too. Why not go wild.)

I think we've done something like the PR thing before, but I'm a bit lost on the details, sorry. (ETA: Rajat's plugin PR creator uses a Spin app in the cloud to create the PR.)

I did it manually locally and the results look okay, a bit doubled up on the top heading, and the code block on the subheads isn't lovely, but perfectly acceptable for compliance purposes I think.

And in dark mode:

[kate-goldenring]

@itowlson this all looks great. IMO, i think we can move this to ready for review and then integrate it with the docs CI as you mention

[itowlson]

After discussion with @kate-goldenring I've moved the forked third-party code into the project (rather than having a separate repo unrelated to the Spin project). I've tried to provide appropriate attribution and credit, and have reproduced the licences and copyright statements. I've done this as a separate commit so we can easily unpick the change if I've done it wrong or I was wrong to do it! Thoughts welcome.