Publish CLI references #118

vdemeester · 2020-05-20T11:11:06Z

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 · 2020-08-14T10:41:15Z

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 · 2020-08-14T10:41:15Z

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 · 2020-08-14T10:41:17Z

@tekton-robot: Closing this issue.

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 · 2020-08-14T12:11:41Z

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

tekton-robot · 2020-08-14T12:11:43Z

@vdemeester: Reopened this issue.

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 · 2020-10-29T15:09:18Z

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 · 2020-11-04T09:41:04Z

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:

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).

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
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

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 · 2020-11-04T09:42:18Z

/cc @vdemeester @popcor255 @AlanGreene

vdemeester · 2020-11-04T09:53:40Z

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

afrittoli · 2020-11-04T10:09:21Z

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.

afrittoli · 2020-11-04T10:54:46Z

Oh, I found the github trees API. It's still GitHub specific, but not brittle:
https://docs.github.com/en/free-pro-team@latest/rest/reference/git#get-a-tree

Example:

$ curl https://api.github.com/repos/tektoncd/pipeline/git/trees/7b5b2fa3ddd99d52baaa10face967b603c6940ee?recursive=true
{
  "sha": "7b5b2fa3ddd99d52baaa10face967b603c6940ee",
  "url": "https://api.github.com/repos/tektoncd/pipeline/git/trees/7b5b2fa3ddd99d52baaa10face967b603c6940ee",
  "tree": [
    {
      "path": ".errcheck.txt",
      "mode": "100644",
      "type": "blob",
      "sha": "64671e21f19ac0282d2edee71e47e8769bb3e3e5",
      "size": 164,
      "url": "https://api.github.com/repos/tektoncd/pipeline/git/blobs/64671e21f19ac0282d2edee71e47e8769bb3e3e5"
    },
    {
      "path": ".gitattributes",
      "mode": "100644",
      "type": "blob",
      "sha": "0c70aa64a330232735ba4e6aa153e3a75ecc28c0",
      "size": 316,
      "url": "https://api.github.com/repos/tektoncd/pipeline/git/blobs/0c70aa64a330232735ba4e6aa153e3a75ecc28c0"
    },
    {
      "path": ".github",
      "mode": "040000",
      "type": "tree",
      "sha": "ed7f1db2cde0f7247f99ff141af1b07ec0b7dbd6",
      "url": "https://api.github.com/repos/tektoncd/pipeline/git/trees/ed7f1db2cde0f7247f99ff141af1b07ec0b7dbd6"
    },
    {
      "path": ".github/ISSUE_TEMPLATE",
      "mode": "040000",
      "type": "tree",
      "sha": "0b9637b5656333499843338c303a23e6f9e3ed81",
      "url": "https://api.github.com/repos/tektoncd/pipeline/git/trees/0b9637b5656333499843338c303a23e6f9e3ed81"
    },
    {
      "path": ".github/ISSUE_TEMPLATE/bug-report.md",
      "mode": "100644",
      "type": "blob",
      "sha": "488bde1fe27f32162764b6215df1b9e1e322c735",
      "size": 506,
      "url": "https://api.github.com/repos/tektoncd/pipeline/git/blobs/488bde1fe27f32162764b6215df1b9e1e322c735"
    },
    {
      "path": ".github/ISSUE_TEMPLATE/feature-request.md",
      "mode": "100644",
      "type": "blob",
      "sha": "876fe90587dbfb0ef5690edcadfa28985d3f5920",
      "size": 459,
      "url": "https://api.github.com/repos/tektoncd/pipeline/git/blobs/876fe90587dbfb0ef5690edcadfa28985d3f5920"
    },
    {
      "path": ".github/ISSUE_TEMPLATE/free-form.md",
      "mode": "100644",
      "type": "blob",
      "sha": "4b924b562a1287e04f5521b0bf6b526cbeccd1dd",
      "size": 60,
      "url": "https://api.github.com/repos/tektoncd/pipeline/git/blobs/4b924b562a1287e04f5521b0bf6b526cbeccd1dd"
    },
    {
(...)

We could first resolve the tag to the sha, using the refs API:

$ curl https://api.github.com/repos/tektoncd/pipeline/git/ref/tags/v0.17.1
{
  "ref": "refs/tags/v0.17.1",
  "node_id": "MDM6UmVmMTQ2NjQxMTUwOnJlZnMvdGFncy92MC4xNy4x",
  "url": "https://api.github.com/repos/tektoncd/pipeline/git/refs/tags/v0.17.1",
  "object": {
    "sha": "9d4d4955b6039aeb5ba5853b37c2ee98631cc171",
    "type": "commit",
    "url": "https://api.github.com/repos/tektoncd/pipeline/git/commits/9d4d4955b6039aeb5ba5853b37c2ee98631cc171"
  }
}

afrittoli · 2020-11-04T11:10:46Z

Just noting that submodules / subtree would require us to use multiple branches on the website, which I'd prefer to avoid.

afrittoli · 2020-11-04T11:12:52Z

I'm leaning towards option (1), with a command line option to allow specifying a local cache of repos, so that the dev workflow may skip the clone step.

Add the doc/cmd folder to add the tkn reference docs to the CLI documentation. Add support for defaulting page title and link title to the filename, if not set, which works OK for tkn. Fixes tektoncd#118 Signed-off-by: Andrea Frittoli <[email protected]>

tekton-robot · 2021-04-27T18:26:39Z

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale with a justification.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close with a justification.
If this issue should be exempted, mark the issue as frozen with /lifecycle frozen with a justification.

/lifecycle stale

Send feedback to tektoncd/plumbing.

tekton-robot · 2021-10-15T02:47:35Z

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale with a justification.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close with a justification.
If this issue should be exempted, mark the issue as frozen with /lifecycle frozen with a justification.

/lifecycle stale

Send feedback to tektoncd/plumbing.

afrittoli · 2021-11-03T18:04:06Z

/remove-lifecycle stale

afrittoli · 2021-11-03T18:04:13Z

/lifecycle frozen

afrittoli · 2021-11-03T18:06:04Z

Sync is implemented now via local clones, with support for local cache too.

tekton-robot added the kind/documentation Categorizes issue or PR as related to documentation. label May 20, 2020

tekton-robot added the lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. label Aug 14, 2020

tekton-robot closed this as completed Aug 14, 2020

tekton-robot reopened this Aug 14, 2020

tekton-robot removed the lifecycle/rotten Denotes an issue or PR that has aged beyond stale and will be auto-closed. label Aug 14, 2020

afrittoli mentioned this issue Nov 9, 2020

Add the tkn reference to the CLI docs #206

Closed

2 tasks

afrittoli added the help wanted Denotes an issue that needs help from a contributor. Must meet "help wanted" guidelines. label Jan 27, 2021

tekton-robot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Apr 27, 2021

afrittoli removed the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label May 13, 2021

tekton-robot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Oct 15, 2021

tekton-robot removed the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Nov 3, 2021

tekton-robot added the lifecycle/frozen Indicates that an issue or PR should not be auto-closed due to staleness. label Nov 3, 2021

xchapter7x added this to Tekton Community Roadmap Sep 20, 2022

xchapter7x moved this to Todo in Tekton Community Roadmap Sep 20, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Publish CLI references #118

Publish CLI references #118

vdemeester commented May 20, 2020

tekton-robot commented Aug 14, 2020

tekton-robot commented Aug 14, 2020

tekton-robot commented Aug 14, 2020

vdemeester commented Aug 14, 2020

tekton-robot commented Aug 14, 2020

afrittoli commented Oct 29, 2020

afrittoli commented Nov 4, 2020

afrittoli commented Nov 4, 2020

vdemeester commented Nov 4, 2020

afrittoli commented Nov 4, 2020

afrittoli commented Nov 4, 2020 •

edited

Loading

afrittoli commented Nov 4, 2020

afrittoli commented Nov 4, 2020

tekton-robot commented Apr 27, 2021

tekton-robot commented Oct 15, 2021

afrittoli commented Nov 3, 2021

afrittoli commented Nov 3, 2021

afrittoli commented Nov 3, 2021

Publish CLI references #118

Publish CLI references #118

Comments

vdemeester commented May 20, 2020

tekton-robot commented Aug 14, 2020

tekton-robot commented Aug 14, 2020

tekton-robot commented Aug 14, 2020

vdemeester commented Aug 14, 2020

tekton-robot commented Aug 14, 2020

afrittoli commented Oct 29, 2020

afrittoli commented Nov 4, 2020

afrittoli commented Nov 4, 2020

vdemeester commented Nov 4, 2020

afrittoli commented Nov 4, 2020

afrittoli commented Nov 4, 2020 • edited Loading

afrittoli commented Nov 4, 2020

afrittoli commented Nov 4, 2020

tekton-robot commented Apr 27, 2021

tekton-robot commented Oct 15, 2021

afrittoli commented Nov 3, 2021

afrittoli commented Nov 3, 2021

afrittoli commented Nov 3, 2021

afrittoli commented Nov 4, 2020 •

edited

Loading