Publish CLI references

[vdemeester]

As part of tekton.dev documentation, we should publish the CLI references of tkn

See https://knative.dev/docs/reference/client/ and https://github.com/tektoncd/cli/tree/master/docs/cmd (reference docs are already generated, we just need to sync them and "present" them)

/kind documentation

[tekton-robot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

/close

Send feedback to tektoncd/plumbing.

[tekton-robot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.
If this issue is safe to close now please do so with /close.

/lifecycle rotten

Send feedback to tektoncd/plumbing.

[tekton-robot]

@tekton-robot: Closing this issue.

Details

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

/close

Send feedback to tektoncd/plumbing.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[vdemeester]

/remove-lifecycle rotten
/remove-lifecycle stale
/reopen

[tekton-robot]

@vdemeester: Reopened this issue.

Details

In response to this:

/remove-lifecycle rotten
/remove-lifecycle stale
/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[afrittoli]

I wonder if an easy way to add this would be to support folder in the sync config.
Alternatively we could add all md files one by one in the sync config, and that should probably address this issue.

[afrittoli]

I've been looking into this and #117, which both require adding a number of generated files generated from a dir to the website.

Because files are generated, the sync process will have to add the heading info.

These are the options of implementation I could think of:

1. Add support for folders to the sync config: e.g.

- name: v0.13.0
  displayName: v0.13.0
  files:
    README.md: _index.md
  folders:
    cmd:
      target: tkn
      index: tkn.md
      filter: "*.md"
      title: tkn
      linkTitle: tkn reference
      weight: 1
      description:  Tekton CLI "tkn" reference

Pros: compact and easy to maintain configuration
Cons: requires to clone full repos since it's not possible with git to discover the list of files in a folder on a remote repo. Headings can be specified once for all files in the folder. The weight will have to be that of the alphabetical order of files (which should be fine).

2. Add support for folders to the sync config, using github workaround to discover files
   Same as (1), but using a trick to list files, which saves us the git clone. The idea is to download a github and scrape the list of folders out of the HTML page

3. Sync files only, add the generated files one by one into the config
   Pros: minimal code changes required, only support for adding heading to the index file. Heading can be specified on a file by file basis.

- name: v0.13.0
  displayName: v0.13.0
  files:
    README.md: _index.md
    cmd/tkn.md:
      target: _index.md
      title: tkn
      linkTitle: tkn reference
      weight: 1
      description:  Tekton CLI "tkn" reference

Cons: since the files are generated, the list may change, and will have to be updated every time there is a change, which could be at release time, but also in between release for "pre-release" docs. To be fair, this problem exists today with regular docs, however since they're added by human it's easier to remember to update the sync config

4. Sync folders via a file-list type of file, that could be generated on the repos we sync from and pulled in as part of the sync process, e.g.

tags:
- name: v0.13.0
  displayName: v0.13.0
  folders:
    cmd:
      list: _list.yaml
      index: tkn.md
      title: tkn
      linkTitle: tkn reference
      weight: 1
      description:  Tekton CLI "tkn" reference
  files:
    README.md: _index.md

Pros: no full clone of repo, easy to maintain on website side
Cons: requires running a post-merge or nightly job on all repo to keep the _list.yaml up to date

[afrittoli]

/cc @vdemeester @popcor255 @AlanGreene

[vdemeester]

(2) seems brittle and tied to GitHub (and how GitHub shows things). What is the "problem" with a full git clone ? 😅

[afrittoli]

Yeah, option (2) is brittle, and would not like that.

There is not problem with a full git clone, but sync we may be syncing from 5 or more repos (pipeline, triggers, cli, dashboard, community and in future chains, catalog, hub and more), it would be a full clone of all those, which takes times and resources.
It's not ideal but ok in CI jobs, less ideal for local dev - since there is no local cache, when trying out things locally we would download 150-200MB now and more in future just to get a few doc files.

We could at least cache repos after the first download to a folder under website so that subsequent runs of the sync command would not need to re-clone. Or we could use git submodules to pull in all those repos via git machinery.