Add kn client commands to the docs

[psschwei]

This came up in Slack today -- essentially, it'd be good to get the kn commands (i.e. this info ) into the docs.

Probably related to #2810

[snneji]

This is a good point. It would make sense to at least provide a link to this info in the reference section.

[rhuss]

The client repo already has a tool to generate reference documentation as already committed in https://github.com/knative/client/tree/main/docs/cmd and has also an option to add some frontmatter to the generated markdown (as it would have been needed for Hugo). I'm not sure which format is required for mkdocs, but the general flow to pick up the reference documentation should be triggered by the build process via the following steps:

• Checkout https://github.com/knative/client at a specific version (tag) in a temp dir
• Run

mkdir -p out/docs/cmd
go run hack/hack/generate-docs.go out true

• Pick up the Markdown files from out/docs/cmd and put it into the right hierarchy for the docs generation process

The generated frontmatter is very rudimentary but we can customize this easily.

[psschwei]

I played around with this a bit today, here's my local preview:

Steps that we'll need to do:

• update nav.yml to include an entry for the main kn.md file (and probably all the other files as well... wondering if there's a way we can generate that dynamically at runtime rather than having to keep nav.yml in sync with the client repo)
• I think we can drop the addFrontMatter function from the client repo, as it doesn't appear mkdocs needs that info
• integrate this into the build script in a nice way. To get it working locally, I made some updates to the build script:

if [ "$BUILD_VERSIONS" == "no" ]; then
  # Build client docs
  git clone --depth 1 https://github.com/knative/client client-latest
  cd client-latest
  mkdir -p out/docs/cmd
  go run hack/generate-docs.go out true
  mv out/docs/cmd ../docs/client
  cd -
  # HEAD to /docs if we're not doing versioning.
  mkdocs build -f mkdocs.yml -d site/docs
else

That skips versioning and also doesn't play very nicely on local, since I have to keep deleting the client-latest directory each time I do the build. But it's a start.

[psschwei]

Screenshot with the front matter function removed:

assuming that looks good to everyone, I can open a PR to remove that from the client repo

[rhuss]

@psschwei thanks a ton, looks great! If the frontmatter is not needed (as it was with Hugo), we can totally remove that part from generate-docs.go. Happy to review and merge a PR for this.

[snneji]

Thanks for working on this @psschwei! Would you like to assign yourself to this issue?

[psschwei]

Thoughts on maybe combining the kn docs into a single page? Right now there's roughly 80 pages, which makes updating the navigation sidebar just a bit tricky.

[rhuss]

A single page might be a bit huge in size and slow to load and render ?

Would it be possible to automate updating the sidebar, too ? Like using a template that is filled in by parsing the md file names ?

[psschwei]

I think that should be doable, although for simplicity's sake probably with the pages in alphabetical order, i.e. this

kn_broker_create.md
kn_broker_delete.md
kn_broker_describe.md
kn_broker_list.md
kn_broker.md

rather than in a hierarchy, as I had tried to do by hand:

kn_broker.md
kn_broker_create.md
kn_broker_delete.md
kn_broker_describe.md
kn_broker_list.md

[rhuss]

Isn't the second list the alphabetical order ? afair, kn_broker.md comes before kn_broker_create.md because . comes lexically before a _.

[psschwei]

At least in my terminal, the sort was the former rather than the latter

$ ls -1 | head
kn_broker_create.md
kn_broker_delete.md
kn_broker_describe.md
kn_broker_list.md
kn_broker.md
kn_channel_create.md
kn_channel_delete.md
kn_channel_describe.md
kn_channel_list.md
kn_channel_list-types.md

[rhuss]

I wouldn't rely on the sorting algo of ls but do a

$ ls -1 | sort | head
kn.md
kn_broker.md
kn_broker_create.md
kn_broker_delete.md
kn_broker_describe.md
kn_broker_list.md
kn_channel.md
kn_channel_create.md
kn_channel_delete.md
kn_channel_describe.md