Create documentation for bundles docs #3804

polskikiel · 2019-04-19T10:43:03Z

Description

Changes proposed in this pull request:

Created documentation for bundles docs

Related issue(s)

aszecowka · 2019-04-23T09:58:11Z

docs/helm-broker/docs/03-01-create-bundles.md

+```
+For now, we support only one entry in the `docs` array.
+
+The Helm Broker can provision a broker which provides its own ServiceClasses. You can see how to provide a documentation for them in the following [document](#details-bundles-docs).


is this link working?

This link will work on kyma-project.io, we must define it in this way because of governance job which blocks links to the not existing documents.

aszecowka · 2019-04-23T10:01:06Z

docs/helm-broker/docs/03-04-bundles-docs.md

+      url: {.Values.addonsRepositoryURL}
+      filter: docs/{class_name}/   # provide filter only if you use the package mode
+___
+# it is prefered to store all of the ClusterDocsTopics definitions in one file


this sentence: "It is preferred" should be moved from the example to the normal documentation paragraph

aszecowka · 2019-04-23T10:04:01Z

docs/helm-broker/docs/03-01-create-bundles.md

+If the `docs/meta.yaml` is specified the Helm Broker tries to create the ClusterDocsTopic for this bundle. Below you can see the example structure of the `meta.yaml` file.
+```
+docs:
+    - template:                     # template describes the ClusterDocsTopic that will be created.


we provided an example, but where I can learn more information about which fields I can provide?

I added a sentence about this below the example

aszecowka · 2019-04-23T11:30:41Z

docs/helm-broker/docs/03-04-bundles-docs.md

+    cms.kyma-project.io/view-context: service-catalog
+  name: {ServiceClass ID}
+spec:
+  displayName: "Slack Connector Add-on"


Should we use placeholder rather than examples?

@klaudiagrz What do you think?

@klaudiagrz ? :)

Yup, I'd go with placeholders as well. @polskikiel please apply this suggestion.

docs/helm-broker/docs/03-01-create-bundles.md

klaudiagrz · 2019-04-23T15:03:39Z

docs/helm-broker/docs/03-01-create-bundles.md

+        sources:                    # list of files to upload as a Asset
+          - type: markdown
+            name: markdown-files    # must be unique within sources
+            mode: package           # defines that file under below 


docs/helm-broker/docs/03-01-create-bundles.md

klaudiagrz · 2019-04-23T15:06:25Z

docs/helm-broker/docs/03-01-create-bundles.md

+            url: abc.pl             # if not provided then Helm broker will inject the full repository URL for this bundle
+            filter: /docs/bundles
+```
+For more information about the fields you can provide and ClusterDocsTopics see the following [file](https://kyma-project.io/docs/components/headless-cms/#custom-resource-clusterdocstopic).


Remove this sentence and provide the link to the CLuterDocsTopics in a place when you mention it for the first time.

docs/helm-broker/docs/03-01-create-bundles.md

kazydek

I added some comments but I would prefer that the topic owner @klaudiagrz had a final look at it :)

docs/helm-broker/docs/03-04-bundles-docs.md

kazydek · 2019-04-24T14:20:50Z

docs/helm-broker/docs/03-04-bundles-docs.md

+    cms.kyma-project.io/view-context: service-catalog
+  name: {ServiceClass ID}
+spec:
+  displayName: "Slack Connector Add-on"


@klaudiagrz ? :)

derberg

this PR is missing information about markdown files, how they should look like, that they should have metadata (metadata is not native for markdown) and what metadata actually and how they will behave
you are kind of missing a nice tutorial, tbh best dock would be if you would have a simple tutorial about bundle creation that would be based on https://github.com/kyma-project/bundles/tree/master/bundles/testing-0.0.1 and this bundle actually should be extended with documentation:
- you could use it as reverence in the tutorial
- so later it can also be used for testing of the catalog and instance views ;)

Co-Authored-By: polskikiel <PolskiKiel@gmail.com>

aszecowka · 2019-04-25T09:10:05Z

/test pre-master-kyma-guard-job

adamwalach · 2019-04-25T09:50:14Z

/test kyma-service-catalog-e2e-tests

adamwalach · 2019-04-25T10:06:11Z

/test kyma-service-catalog-e2e-tests

adamwalach · 2019-04-25T10:17:25Z

/test kyma-service-catalog-e2e-tests

adamwalach · 2019-04-25T11:39:14Z

/test kyma-service-catalog-e2e-tests

adamwalach · 2019-04-25T12:15:40Z

/test kyma-service-catalog-e2e-tests

polskikiel · 2019-04-25T12:58:31Z

@derberg I created two follow-up tasks to address these things:

polskikiel · 2019-04-25T12:58:38Z

/retest

polskikiel · 2019-04-25T13:10:30Z

/retest

klaudiagrz

This is not the end of the review. Let's discuss the structure of the document.

docs/helm-broker/docs/03-01-create-bundles.md

klaudiagrz · 2019-04-26T11:28:24Z

docs/helm-broker/docs/03-01-create-bundles.md

+## docs directory
+
+In the `docs` directory, provide documentation for your bundle and for the wrapped Helm chart. You can also define a `meta.yaml` file inside the `docs` folder, which provides information on how documentation for the bundle is uploaded.
+As the Helm Broker is installed as a ClusterServiceBroker, documentation for bundles is provided using ClusterDocsTopics.


Please add a link to the ClusterDocsTopic.

klaudiagrz · 2019-04-26T11:30:18Z

docs/helm-broker/docs/03-01-create-bundles.md

+
+In the `docs` directory, provide documentation for your bundle and for the wrapped Helm chart. You can also define a `meta.yaml` file inside the `docs` folder, which provides information on how documentation for the bundle is uploaded.
+As the Helm Broker is installed as a ClusterServiceBroker, documentation for bundles is provided using ClusterDocsTopics.
+If you specify the `meta.yaml`, the Helm Broker creates a ClusterDocsTopic for this bundle based on the `meta.yaml` file. The example structure of the `meta.yaml` file looks as follows:


I'd remove this whole sentence - meta.yaml is obligatory.

klaudiagrz · 2019-04-26T11:33:31Z

docs/helm-broker/docs/03-01-create-bundles.md

+
+>**NOTE:** Currently you can provide only one entry in the `docs` array. In the future we will enable many entries in case of many charts in one bundle.
+
+The `meta.yaml` file contains the specification of the ClusterDocsTopic. To learn more about it, read [this](/components/headless-cms/#custom-resource-clusterdocstopic) document.


I'd move this sentence above the table.

docs/helm-broker/docs/03-01-create-bundles.md

klaudiagrz · 2019-04-26T11:46:11Z

docs/helm-broker/docs/03-04-bundles-docs.md

+    cms.kyma-project.io/view-context: service-catalog
+  name: {ServiceClass ID}
+spec:
+  displayName: "Slack Connector Add-on"


Yup, I'd go with placeholders as well. @polskikiel please apply this suggestion.

docs/helm-broker/docs/03-04-bundles-docs.md

klaudiagrz · 2019-04-26T14:00:49Z

docs/helm-broker/docs/03-04-bundles-docs.md

+Store documentation for each Service Class in the `docs/{class_name}` directory which corresponds to the value of the **filter** parameter in the ClusterDocsTopic definition.
+
+
+During the provisioning process, the Helm Broker pushes the **addonRepositoryURL** variable into the chart. The **addonsRepositoryURL** points to your bundle compressed to a `.tgz` file.


I'm not sure about this paragraph. To be honest, I would totally omit this info. @PK85 let us know what you think :)

polskikiel · 2019-04-26T14:01:35Z

/retest

kyma-bot · 2019-04-26T14:03:04Z

@polskikiel: The following test failed, say /retest to rerun them all:

Test name	Commit	Details	Rerun command
kyma-service-catalog-e2e-tests	`4c5793c`	link	`/test kyma-service-catalog-e2e-tests`

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. I understand the commands that are listed here.

adamwalach · 2019-04-30T07:18:07Z

/test kyma-service-catalog-e2e-tests

polskikiel requested review from bszwarc, kazydek, klaudiagrz, mmitoraj and tomekpapiernik as code owners April 19, 2019 10:43

aszecowka suggested changes Apr 23, 2019

View reviewed changes

Provide documentation for bundles docs

df71632

aszecowka approved these changes Apr 23, 2019

View reviewed changes

klaudiagrz reviewed Apr 23, 2019

View reviewed changes

kazydek reviewed Apr 24, 2019

View reviewed changes

derberg reviewed Apr 24, 2019

View reviewed changes

polskikiel and others added 2 commits April 25, 2019 10:37

Apply suggestions from code review

a073a6f

Co-Authored-By: polskikiel <PolskiKiel@gmail.com>

Improve docs after review

d0e927f

polskikiel mentioned this pull request Apr 25, 2019

Provide documentation for the testing bundle kyma-project/addons#79

Closed

klaudiagrz reviewed Apr 26, 2019

View reviewed changes

Improve docs

82012d0

klaudiagrz reviewed Apr 26, 2019

View reviewed changes

klaudiagrz approved these changes Apr 26, 2019

View reviewed changes

improve docs

fe3c3fa

polskikiel merged commit 88955de into kyma-project:master Apr 29, 2019

polskikiel deleted the bundles-docs-docs branch April 29, 2019 08:13


		>NOTE: Currently you can provide only one entry in the `docs` array. In the future we will enable many entries in case of many charts in one bundle.

		The `meta.yaml` file contains the specification of the ClusterDocsTopic. To learn more about it, read [this](/components/headless-cms/#custom-resource-clusterdocstopic) document.

		Store documentation for each Service Class in the `docs/{class_name}` directory which corresponds to the value of the filter parameter in the ClusterDocsTopic definition.


		During the provisioning process, the Helm Broker pushes the addonRepositoryURL variable into the chart. The addonsRepositoryURL points to your bundle compressed to a `.tgz` file.

Create documentation for bundles docs #3804

Create documentation for bundles docs #3804

Conversation

polskikiel commented Apr 19, 2019

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

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

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

kazydek left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

derberg left a comment

Choose a reason for hiding this comment

aszecowka commented Apr 25, 2019

adamwalach commented Apr 25, 2019

adamwalach commented Apr 25, 2019

adamwalach commented Apr 25, 2019

adamwalach commented Apr 25, 2019

adamwalach commented Apr 25, 2019

polskikiel commented Apr 25, 2019

polskikiel commented Apr 25, 2019

polskikiel commented Apr 25, 2019

klaudiagrz 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

Choose a reason for hiding this comment

polskikiel commented Apr 26, 2019

kyma-bot commented Apr 26, 2019 • edited Loading

adamwalach commented Apr 30, 2019

kyma-bot commented Apr 26, 2019 •

edited

Loading