Import documentation #27

sftim · 2021-03-16T20:32:19Z

A quick PR to import documentation from https://github.com/shipwright-io/build/tree/master/docs

sftim · 2021-03-16T20:32:34Z

sftim · 2021-03-16T20:33:59Z

/kind documentation

zhangtbj · 2021-03-17T07:07:39Z

Can we just link the document from shipwright/build directly instead copy and store a copy in the website repo?

I think they are duplicates and we have to update/maintain them if there is any update on the shipwright/build side (I think it will happen frequently this year.)

adambkaplan · 2021-03-17T16:04:08Z

Can we just link the document from shipwright/build directly instead copy and store a copy in the website repo?

I think they are duplicates and we have to update/maintain them if there is any update on the shipwright/build side (I think it will happen frequently this year.)

@zhangtbj I share your concern about having duplicate docs. shipwright.io is our user-facing website, therefore user-facing documentation should live there long term.

We can flip our contributing guide and ask new features to have PRs opened against shipwright-io/website. Upstream Kubernetes is large enough that a dedicated SIG tracks features and helps draft docs [1]. At our state is to too much to ask developers to draft feature docs?

[1] https://kubernetes.io/docs/contribute/new-content/new-features/

adambkaplan

@sftim thank you for the PR!

I noticed that the api docs don't generate their own sub-level in the sidebar, so for now everything is under one level. I think if you add _index.md files in the subfolders, we get those sub-headers for free?

Regarding segments, I think for this initial import we can split into two:

"Concepts"
"Configuration"

The latter exposes a lot of fine tuning that a new Shipwright user would not necessarily use.

P.S. miss you from sig-docs, as you can see I've been busy lately 👋.

adambkaplan · 2021-03-17T16:17:23Z

content/en/docs/_index.md

@@ -3,20 +3,136 @@ title: "Documentation"
 linkTitle: "Documentation"


Note to self - the imported article is a true overview. In the long term we will want this page to serve as a table of contents, so keeping the "Documentation" title is appropriate.

content/en/docs/api/build.md

adambkaplan · 2021-03-17T16:19:13Z

content/en/docs/authentication.md

@@ -0,0 +1,170 @@
+---
+title: Authentication during builds


I think this too can live under "concepts"

adambkaplan · 2021-03-17T16:20:51Z

content/en/docs/controller_flow.md

+title: Control flow
+---
+
+The following image illustrate the interactions between the Build, BuildRun controller and the Tekton Pipeline controller:


This is a bit more of an architecture article, and not meant for end users. For now I say it can live in shipwright-io/build

adambkaplan · 2021-03-17T16:22:19Z

content/en/docs/metrics.md

@@ -0,0 +1,84 @@
+---
+title: Build Controller Metrics


Note that this is geared towards installation/configuration of the controller. More is coming in this regard as we are tuning our installation process.

adambkaplan · 2021-03-17T16:22:40Z

content/en/docs/profiling.md

@@ -0,0 +1,40 @@
+---
+title: Build Controller Profiling


Likewise, this is an install/configuration article.

adambkaplan · 2021-03-17T16:22:58Z

content/en/docs/configuration.md

@@ -0,0 +1,23 @@
+---
+title: "Configuration"


This is an install/configuration article

sftim · 2021-03-17T17:33:20Z

Can we just link the document from shipwright/build directly instead copy and store a copy in the website repo?

Not super easily. Hugo Markdown and the documentation in shipwright/build are a different format.

I agree with #27 (comment) about migrating docs to this repo (so: remove the Markdown pages from the other repo when this goes live).

If you keep them in the other repo, you need to trigger some kind of dependent Netlify build when PRs in shipwright/build touch docs, and fail the CI test if the Netlify preview build fails. I can build that for you but it's loads more effort than moving a few Markdown files to a different repo.

sftim · 2021-03-17T17:34:00Z

BTW, I've marked this PR to allow maintainer edits. Please feel free to commit directly here if you're a maintainer and you're confident that you know the change you want to make.

sftim · 2021-03-17T17:43:50Z

I noticed that the api docs don't generate their own sub-level in the sidebar, so for now everything is under one level. I think if you add _index.md files in the subfolders, we get those sub-headers for free?

Indeed. I was hoping another contributor would be willing to add an API overview - maybe after this merges? I know there's room for further tidying but as Voltaire never quite said, “the perfect is the enemy of the deployed”.

adambkaplan · 2021-03-17T18:23:40Z

Indeed. I was hoping another contributor would be willing to add an API overview - maybe after this merges? I know there's room for further tidying but as Voltaire never quite said, “the perfect is the enemy of the deployed”.

Agree. We've also highlighted a path to organizing the docs in #24 - this import gives us something real to iterate on.

A simple contact page, needs more work.

Spelling correction for link title.

adambkaplan

/approve

Added spelling correction.

content/en/docs/api/build.md

openshift-ci-robot · 2021-03-18T12:41:16Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: adambkaplan

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~~ [adambkaplan]

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

adambkaplan · 2021-03-23T12:44:51Z

@sftim in Monday's call, the community expressed strong desire for keeping documentation closer to the code repositories (ex - github.com/shipwright-io/build), and syncing that content here. Tekton has an interesting script that facilitates this process [1].

@zhangtbj @qu1queee @gabemontero I'd like to propose the following (will also send this to the dev mailing list):

Merge this PR so we have a base level of content to work with.
Update the folder structure and file front matter in website so the docs are structured and presented to our liking.
Add the appropriate front matter to the docs in build
Incorporate the Tekton sync script (with adjustments as needed) into website.

[1] https://github.com/tektoncd/website/tree/main/sync

gabemontero · 2021-03-23T12:46:20Z

+1 @adambkaplan

sftim · 2021-03-23T12:58:22Z

We can fetch the content over from https://github.com/shipwright-io/build during a build of this repo, so that this repo doesn't hold a synced copy but it still previews OK locally, on Netlify, and publishes how we expect.

BTW what we lose there is CI/CD: how do we ensure that a documentation change to https://github.com/shipwright-io/build is valid?
We don't have that now so there's no regression.

adambkaplan · 2021-03-23T13:26:23Z

BTW what we lose there is CI/CD: how do we ensure that a documentation change to https://github.com/shipwright-io/build is valid?
We don't have that now so there's no regression.

I think we can take a near term/long term strategy here

Near term: keep a synced copy in git, update via pull requests.
Medium term: Add a "docs" GitHub action in shipwright-io/build (and future repositories) which checks out the website code, runs the sync, and then has hugo generate the static content. Failures here will need to have clear messaging so contributors know what went wrong and how to fix it.
Long term: Stop syncing content to git, switch to nightly deployments.

My hope is that with the docs GitHub action, we will catch 90% of bugs that would cause the Netlify deployment to fail from synced content.

zhangtbj · 2021-03-24T02:48:38Z

+1, thanks!

adambkaplan · 2021-03-24T15:31:16Z

/lgtm

openshift-ci-robot requested review from xiujuan95 and zhangtbj March 16, 2021 20:32

openshift-ci-robot added the kind/documentation Categorizes issue or PR as related to documentation. label Mar 16, 2021

adambkaplan requested changes Mar 17, 2021

View reviewed changes

adambkaplan mentioned this pull request Mar 17, 2021

March 22, 2021 Community Meeting shipwright-io/build#673

Closed

openshift-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Mar 17, 2021

sftim added 3 commits March 17, 2021 18:33

Import docs from build repository

42752d7

Tidy documentation section

b232ff0

Add contact page

49a8c7a

A simple contact page, needs more work.

openshift-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Mar 17, 2021

Fix spelling - "Profiling"

2a6f561

Spelling correction for link title.

adambkaplan approved these changes Mar 18, 2021

View reviewed changes

content/en/docs/api/build.md Show resolved Hide resolved

openshift-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Mar 18, 2021

This was referenced Mar 24, 2021

Sync Code-Driven Documentation to Website #29

Open

Add Docs Check to Pull Request CI shipwright-io/build#692

Open

openshift-ci-robot assigned adambkaplan Mar 24, 2021

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Mar 24, 2021

openshift-merge-robot merged commit ff879c1 into shipwright-io:master Mar 24, 2021

sftim deleted the 20210316_initial_docs branch March 24, 2021 16:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Import documentation #27

Import documentation #27

sftim commented Mar 16, 2021

sftim commented Mar 16, 2021

sftim commented Mar 16, 2021

zhangtbj commented Mar 17, 2021

adambkaplan commented Mar 17, 2021

adambkaplan left a comment

adambkaplan Mar 17, 2021

adambkaplan Mar 17, 2021

adambkaplan Mar 17, 2021

sftim Mar 17, 2021

adambkaplan Mar 17, 2021

adambkaplan Mar 17, 2021

adambkaplan Mar 17, 2021

sftim commented Mar 17, 2021

sftim commented Mar 17, 2021

sftim commented Mar 17, 2021

adambkaplan commented Mar 17, 2021

adambkaplan left a comment

openshift-ci-robot commented Mar 18, 2021

adambkaplan commented Mar 23, 2021

gabemontero commented Mar 23, 2021

sftim commented Mar 23, 2021

adambkaplan commented Mar 23, 2021

zhangtbj commented Mar 24, 2021

adambkaplan commented Mar 24, 2021

		@@ -3,20 +3,136 @@ title: "Documentation"
		linkTitle: "Documentation"

Import documentation #27

Import documentation #27

Conversation

sftim commented Mar 16, 2021

sftim commented Mar 16, 2021

sftim commented Mar 16, 2021

zhangtbj commented Mar 17, 2021

adambkaplan commented Mar 17, 2021

adambkaplan left a comment

Choose a reason for hiding this comment

adambkaplan Mar 17, 2021

Choose a reason for hiding this comment

adambkaplan Mar 17, 2021

Choose a reason for hiding this comment

adambkaplan Mar 17, 2021

Choose a reason for hiding this comment

sftim Mar 17, 2021

Choose a reason for hiding this comment

adambkaplan Mar 17, 2021

Choose a reason for hiding this comment

adambkaplan Mar 17, 2021

Choose a reason for hiding this comment

adambkaplan Mar 17, 2021

Choose a reason for hiding this comment

sftim commented Mar 17, 2021

sftim commented Mar 17, 2021

sftim commented Mar 17, 2021

adambkaplan commented Mar 17, 2021

adambkaplan left a comment

Choose a reason for hiding this comment

openshift-ci-robot commented Mar 18, 2021

adambkaplan commented Mar 23, 2021

gabemontero commented Mar 23, 2021

sftim commented Mar 23, 2021

adambkaplan commented Mar 23, 2021

zhangtbj commented Mar 24, 2021

adambkaplan commented Mar 24, 2021