Build client docs #4623

psschwei · 2022-01-10T17:37:59Z

Proposed Changes

Add documentation for the kn client to the docs.

Fixes #4430

netlify · 2022-01-10T17:38:07Z

✔️ Deploy Preview for knative ready!

🔨 Explore the source changes: 3d7cccb

🔍 Inspect the deploy log: https://app.netlify.com/sites/knative/deploys/61df33e4d4963500079f2b61

😎 Browse the preview: https://deploy-preview-4623--knative.netlify.app/development/reference/client

psschwei · 2022-01-10T20:30:09Z

On test failures:

Verify mkdocs strict fails because the client docs aren't in the repo by default (they're copied over as part of the build process). Perhaps we need to update the mkdocs-strict-verify job? @csantanapr @snneji any objections?
The various netlify jobs are failing with a cannot find package "." error:

3:08:36 PM: + pushd /tmp/tmp.Z37VtDIguA/client-main
3:08:36 PM: /tmp/tmp.Z37VtDIguA/client-main /opt/build/repo
3:08:36 PM: + go run hack/generate-docs.go out
3:08:38 PM: vendor/k8s.io/client-go/plugin/pkg/client/auth/exec/metrics.go:21:2: cannot find package "." in:
3:08:38 PM: 	/tmp/tmp.Z37VtDIguA/client-main/vendor/io/fs
3:08:38 PM: 
3:08:38 PM: ────────────────────────────────────────────────────────────────
3:08:38 PM:   "build.command" failed                                        
3:08:38 PM: ────────────────────────────────────────────────────────────────

The build script works fine on my local system, so not sure what exactly is the problem on the remote... will keep looking into it.
Update: seems to be something on the Netlify side, but I know very little about that side of things...

psschwei · 2022-01-10T22:59:02Z

Update: looks like I need to make sure I'm using go1.16 for all these builds...

psschwei · 2022-01-11T01:11:35Z

#4624 fixes the Verify failure

snneji

Thanks for adding this! Just a few items in the nav need to be tweaked.

snneji · 2022-01-11T14:20:38Z

config/nav.yml

+            - kn source: reference/client/kn_source.md
+            - kn source create: reference/client/kn_source_apiserver_create.md
+            - kn source delete: reference/client/kn_source_apiserver_delete.md
+            - kn source describe: reference/client/kn_source_apiserver_describe.md
+            - kn source apiserver:
+              - kn source apiserver: reference/client/kn_source_apiserver.md
+              - kn source apiserver list: reference/client/kn_source_apiserver_list.md
+              - kn source apiserver update: reference/client/kn_source_apiserver_update.md


Suggested change

- kn source: reference/client/kn_source.md

- kn source create: reference/client/kn_source_apiserver_create.md

- kn source delete: reference/client/kn_source_apiserver_delete.md

- kn source describe: reference/client/kn_source_apiserver_describe.md

- kn source apiserver:

- kn source apiserver: reference/client/kn_source_apiserver.md

- kn source apiserver list: reference/client/kn_source_apiserver_list.md

- kn source apiserver update: reference/client/kn_source_apiserver_update.md

- kn source: reference/client/kn_source.md

- kn source apiserver:

- kn source apiserver: reference/client/kn_source_apiserver.md

- kn source apiserver create: reference/client/kn_source_apiserver_create.md

- kn source apiserver delete: reference/client/kn_source_apiserver_delete.md

- kn source apiserver describe: reference/client/kn_source_apiserver_describe.md

- kn source apiserver list: reference/client/kn_source_apiserver_list.md

- kn source apiserver update: reference/client/kn_source_apiserver_update.md

APIServerSource create, delete, and describe links need to be moved down under the kn source apiserver section.

snneji · 2022-01-11T14:21:56Z

config/nav.yml

+              - kn source apiserver: reference/client/kn_source_apiserver.md
+              - kn source apiserver list: reference/client/kn_source_apiserver_list.md
+              - kn source apiserver update: reference/client/kn_source_apiserver_update.md
+              - kn source binding: reference/client/kn_source_binding.md


Suggested change

- kn source binding: reference/client/kn_source_binding.md

- kn source binding:

- kn source binding: reference/client/kn_source_binding.md

Create a section for kn source binding

snneji · 2022-01-11T16:52:17Z

I'm wondering if it is possible to have some of these on the same page? For example, grouping all kn broker commands on one page with sections for create, delete, describe, list. Maybe doing the same for all of the nested groups of commands like kn channel, kn source etc?

I don't know if this is possible since all the files in the client repo are on separate pages.

psschwei · 2022-01-11T17:05:01Z

I'm wondering if it is possible to have some of these on the same page? For example, grouping all kn broker commands on one page with sections for create, delete, describe, list. Maybe doing the same for all of the nested groups of commands like kn channel, kn source etc?

I don't know if this is possible since all the files in the client repo are on separate pages.

@rhuss can probably answer better than I can, but my understanding is that the change would need to be made on the source files, unless we wanted to try concatenating them in the build script (though I'd really rather not)

psschwei · 2022-01-11T17:53:30Z

Discussed in WG: using a single page that links to the client/docs/cmd/kn.md in the reference section (with a variable for the branch to be filled when building the site)

psschwei · 2022-01-11T22:05:17Z

Linking to Github proved to be a lot easier than I thought... @snneji let me know if the page I added looks ok or if the text should be tweaked a bit.

rhuss · 2022-01-12T08:22:57Z

The preview referenced above does not reflect the recent changes. Do we need to regenerate the preview or is this done automatically ?

psschwei · 2022-01-12T14:06:24Z

Looks like the preview didn't default to the development branch... here's a proper link: https://deploy-preview-4623--knative.netlify.app/development/reference/client/

rhuss · 2022-01-12T18:51:14Z

I think this is a first step in the right direction (so happy to merge this), but eventually, I really would love a tighter and more seamless integration that is easier to consume for the reader.

Let me check if I can consolidate the markdown generation into fewer pages and generate a nice drill-down navigation.

rhuss · 2022-01-12T18:54:18Z

FYI, if I select 1.1 in the rendered preview, I don't see a "Client" item in the "Reference" navigation bar (guess this will work only for future versions ?)

psschwei · 2022-01-12T19:04:16Z

I think this is a first step in the right direction (so happy to merge this), but eventually, I really would love a tighter and more seamless integration that is easier to consume for the reader.

+1

FYI, if I select 1.1 in the rendered preview, I don't see a "Client" item in the "Reference" navigation bar (guess this will work only for future versions ?)

It needs to get cherry picked into the different release branches, which we can do once we merge.

snneji · 2022-01-12T19:45:56Z

docs/reference/client/README.md

+Please see the `kn` documentation available at:
+
+[{{ clientdocs() }}]({{ clientdocs() }}){target=_blank}


Suggested change

Please see the `kn` documentation available at:

[{{ clientdocs() }}]({{ clientdocs() }}){target=_blank}

See the [`kn` documentation]({{ clientdocs() }}){target=_blank} in GitHub.

I think it is better for accessibility purposes to have link text instead of a URL. Also it is in our style guide.

Also, should this link go to the 1.1 branch? At the moment, from the preview it looks like it's going to main.

Also, should this link go to the 1.1 branch? At the moment, from the preview it looks like it's going to main.

It should get updated automatically depending on which branch is being built, similar to how the serving/eventing yaml links in the getting started guide are handled.

Ah I see now! Since we're in main it'll go to main.

snneji · 2022-01-12T19:54:40Z

@rhuss

I think this is a first step in the right direction (so happy to merge this), but eventually, I really would love a tighter and more seamless integration that is easier to consume for the reader.

Let me check if I can consolidate the markdown generation into fewer pages and generate a nice drill-down navigation.

That would be great!

snneji · 2022-01-13T12:58:41Z

/cherrypick release-1.1

knative-prow-robot · 2022-01-13T12:58:42Z

@snneji: once the present PR merges, I will cherry-pick it on top of release-1.1 in a new PR and assign it to you.

In response to this:

/cherrypick release-1.1

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.

knative-prow-robot · 2022-01-13T12:59:12Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: psschwei, snneji

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [psschwei,snneji]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

knative-prow-robot · 2022-01-13T13:00:55Z

@snneji: #4623 failed to apply on top of branch "release-1.1":

Applying: build kn docs
Using index info to reconstruct a base tree...
M	hack/build.sh
Falling back to patching base and 3-way merge...
Auto-merging hack/build.sh
CONFLICT (content): Merge conflict in hack/build.sh
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
Patch failed at 0001 build kn docs
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".

In response to this:

/cherrypick release-1.1

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.

knative-prow-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jan 10, 2022

knative-prow-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Jan 10, 2022

psschwei force-pushed the kn-docs branch from e7c5223 to 4981a6b Compare January 10, 2022 21:30

psschwei mentioned this pull request Jan 10, 2022

Adds client docs to strict verify action #4624

Closed

psschwei changed the title ~~[WIP] Build client docs~~ Build client docs Jan 10, 2022

knative-prow-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jan 10, 2022

build kn docs

04c2a45

psschwei force-pushed the kn-docs branch from 4981a6b to 04c2a45 Compare January 11, 2022 01:26

snneji suggested changes Jan 11, 2022

View reviewed changes

knative-prow-robot assigned snneji Jan 11, 2022

navigation tweaks

72e4058

link to github version of kn docs

c406d33

knative-prow-robot added size/S Denotes a PR that changes 10-29 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Jan 11, 2022

psschwei added 2 commits January 11, 2022 17:06

removing unneeded envvar

b1c346d

removing go

ea5d910

snneji reviewed Jan 12, 2022

View reviewed changes

style

3d7cccb

snneji approved these changes Jan 13, 2022

View reviewed changes

knative-prow-robot added the lgtm Indicates that a PR is ready to be merged. label Jan 13, 2022

knative-prow-robot merged commit e9713b1 into knative:main Jan 13, 2022

psschwei mentioned this pull request Jan 13, 2022

[release 1.1] Add client docs to website #4632

Merged

psschwei deleted the kn-docs branch March 10, 2022 16:39

psschwei mentioned this pull request Oct 19, 2022

Automate CLI / func docs generation #5285

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Build client docs #4623

Build client docs #4623

psschwei commented Jan 10, 2022 •

edited

Loading

netlify bot commented Jan 10, 2022 •

edited

Loading

psschwei commented Jan 10, 2022 •

edited

Loading

psschwei commented Jan 10, 2022

psschwei commented Jan 11, 2022

snneji left a comment

snneji Jan 11, 2022

snneji Jan 11, 2022

snneji Jan 11, 2022

snneji Jan 11, 2022

snneji commented Jan 11, 2022 •

edited

Loading

psschwei commented Jan 11, 2022

psschwei commented Jan 11, 2022

psschwei commented Jan 11, 2022

rhuss commented Jan 12, 2022

psschwei commented Jan 12, 2022 •

edited

Loading

rhuss commented Jan 12, 2022

rhuss commented Jan 12, 2022

psschwei commented Jan 12, 2022

snneji Jan 12, 2022

snneji Jan 12, 2022

snneji Jan 12, 2022

psschwei Jan 12, 2022

snneji Jan 13, 2022

snneji commented Jan 12, 2022

snneji commented Jan 13, 2022

knative-prow-robot commented Jan 13, 2022

knative-prow-robot commented Jan 13, 2022

knative-prow-robot commented Jan 13, 2022

	- kn source binding: reference/client/kn_source_binding.md
	- kn source binding:
	- kn source binding: reference/client/kn_source_binding.md

		Please see the `kn` documentation available at:

		[{{ clientdocs() }}]({{ clientdocs() }}){target=_blank}

Build client docs #4623

Build client docs #4623

Conversation

psschwei commented Jan 10, 2022 • edited Loading

Proposed Changes

netlify bot commented Jan 10, 2022 • edited Loading

psschwei commented Jan 10, 2022 • edited Loading

psschwei commented Jan 10, 2022

psschwei commented Jan 11, 2022

snneji left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

snneji commented Jan 11, 2022 • edited Loading

psschwei commented Jan 11, 2022

psschwei commented Jan 11, 2022

psschwei commented Jan 11, 2022

rhuss commented Jan 12, 2022

psschwei commented Jan 12, 2022 • edited Loading

rhuss commented Jan 12, 2022

rhuss commented Jan 12, 2022

psschwei commented Jan 12, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

snneji commented Jan 12, 2022

snneji commented Jan 13, 2022

knative-prow-robot commented Jan 13, 2022

knative-prow-robot commented Jan 13, 2022

knative-prow-robot commented Jan 13, 2022

psschwei commented Jan 10, 2022 •

edited

Loading

netlify bot commented Jan 10, 2022 •

edited

Loading

psschwei commented Jan 10, 2022 •

edited

Loading

snneji commented Jan 11, 2022 •

edited

Loading

psschwei commented Jan 12, 2022 •

edited

Loading