CRD documentation list all versions #17421

k15r · 2023-04-27T16:12:39Z

Description

Changes proposed in this pull request:

create one section per crd version
create one table per spec and status
add "type" column with indicator if mandatory

Related issue(s)

status

netlify · 2023-04-27T16:12:46Z

✅ Deploy Preview for kyma-project-docs-preview ready!

Name	Link
🔨 Latest commit	`f09c35b`
🔍 Latest deploy log	https://app.netlify.com/sites/kyma-project-docs-preview/deploys/645a23b153f9b0000841b0f6
😎 Deploy Preview	https://deploy-preview-17421--kyma-project-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

a-thaler · 2023-04-28T07:05:36Z

docs/05-technical-reference/00-custom-resources/telemetry-03-tracepipeline.md

+<!-- TracePipeline v1alpha1 telemetry.kyma-project.io -->
+| Parameter         | Type | Description                                   |
+| ------------------| ---- | --------------------------------------------- |
+| **spec.output** | object | Defines a destination for shipping trace data. Only one can be defined per pipeline. |


Can you remove the "spec." prefix, it is redundant and will reduce the width of the column

a-thaler · 2023-04-28T07:07:30Z

Could you ad the "required" flag behind the type so that we have covered all requirements already. That would be great :)

k15r · 2023-04-28T07:25:01Z

Could you ad the "required" flag behind the type so that we have covered all requirements already. That would be great :)

let me try. but as this tool uses a rather basic way to "parse" openapi it will not be nice

a-thaler · 2023-05-02T09:42:40Z

docs/05-technical-reference/00-custom-resources/evnt-01-subscription.md

+<!-- Subscription v1alpha1 eventing.kyma-project.io -->
+| Parameter         | Type | Description                                   |
+| ------------------| ---- | --------------------------------------------- |
+| **** | object | SubscriptionSpec defines the desired state of Subscription. |


The "spec" root attribute need to be excluded from generation

a-thaler · 2023-05-02T09:44:09Z

docs/05-technical-reference/00-custom-resources/telemetry-01-logpipeline.md

+| ------------------| ---- | --------------------------------------------- |
+| **** | object | Defines the desired state of LogPipeline |
+| **files** | Provides file content to be consumed by a LogPipeline configuration | files |


The description is in second column...

templating

mmitoraj

Hi, nice new features :) I have a few suggestions:

Please remove all parameters' names from the Description to avoid duplication. For example, instead of:

| **backend.emshash** | integer | Emshash defines the hash for the Subscription in EventType. |

write:

| **backend.emshash** | integer | Defines the hash for the Subscription in EventType. |

For me, the information if something is required doesn't look good in the Type column. How about adding it in parentheses in a new line after the parameter name in the Parameter column? For example:

 | **protocolsettings.webhookAuth.tokenUrl** (required) | string | TokenURL defines token URL for OAuth2 |

It should go to a new line under the parameter name, right?

I added a few suggestions to the descriptions themselves but is there a point of doing that in the autogenerated document? Can I review those in the source files?

mmitoraj · 2023-05-08T09:40:31Z

docs/05-technical-reference/00-custom-resources/evnt-01-subscription.md

+
+| Parameter | Type | Description |
+| ---- | ----------- | ---- |
+| **config** | map[string]string | Config defines the configurations that can be applied to the eventing backend. |


"map[string]string" in the preview displays as "mapstringstring". I guess it should look differently, doesn't it?

mmitoraj · 2023-05-08T10:13:48Z

docs/05-technical-reference/00-custom-resources/evnt-01-subscription.md

+| ---- | ----------- | ---- |
+| **config** | map[string]string | Config defines the configurations that can be applied to the eventing backend. |
+| **id** | string | ID is the unique identifier of Subscription, read-only. |
+| **sink** | string **required** | Sink defines endpoint of the subscriber |


mmitoraj · 2023-05-08T10:13:58Z

docs/05-technical-reference/00-custom-resources/evnt-01-subscription.md

+| **sink** | string **required** | Sink defines endpoint of the subscriber |
+| **source** | string **required** | Source Defines the source of the event originated from. |
+| **typeMatching** | string | TypeMatching defines the type of matching to be done for the event types. |
+| **types** | []string | Types defines the list of event names for the topics we need to subscribe for messages. |


Is "[ ] string" a string array?

mmitoraj · 2023-05-08T10:23:08Z

docs/05-technical-reference/00-custom-resources/evnt-01-subscription.md

+| Parameter | Type | Description |
+| ---- | ----------- | ---- |
+| **config** | map[string]string | Config defines the configurations that can be applied to the eventing backend. |
+| **id** | string | ID is the unique identifier of Subscription, read-only. |


mmitoraj · 2023-05-08T10:23:45Z

docs/05-technical-reference/00-custom-resources/evnt-01-subscription.md

+| **config** | map[string]string | Config defines the configurations that can be applied to the eventing backend. |
+| **id** | string | ID is the unique identifier of Subscription, read-only. |
+| **sink** | string **required** | Sink defines endpoint of the subscriber |
+| **source** | string **required** | Source Defines the source of the event originated from. |


mmitoraj · 2023-05-08T10:25:35Z

docs/05-technical-reference/00-custom-resources/evnt-01-subscription.md

+| **id** | string | ID is the unique identifier of Subscription, read-only. |
+| **sink** | string **required** | Sink defines endpoint of the subscriber |
+| **source** | string **required** | Source Defines the source of the event originated from. |
+| **typeMatching** | string | TypeMatching defines the type of matching to be done for the event types. |


mmitoraj · 2023-05-08T10:27:25Z

docs/05-technical-reference/00-custom-resources/evnt-01-subscription.md

+| **sink** | string **required** | Sink defines endpoint of the subscriber |
+| **source** | string **required** | Source Defines the source of the event originated from. |
+| **typeMatching** | string | TypeMatching defines the type of matching to be done for the event types. |
+| **types** | []string | Types defines the list of event names for the topics we need to subscribe for messages. |


mmitoraj

In the Description column links don’t display correctly and the formatting is broken (code font, bold, etc.).

mmitoraj · 2023-05-08T13:53:01Z

docs/05-technical-reference/00-custom-resources/telemetry-02-logparser.md

+
+| Parameter | Type | Description |
+| ---- | ----------- | ---- |
+| **parser**  | string | \[Fluent Bit Parsers\]\(https://docs\.fluentbit\.io/manual/pipeline/parsers\)\. The parser specified here has no effect until it is referenced by a \[Pod annotation\]\(https://docs\.fluentbit\.io/manual/pipeline/filters/kubernetes\#kubernetes\-annotations\) on your workload or by a \[Parser Filter\]\(https://docs\.fluentbit\.io/manual/pipeline/filters/parser\) defined in a pipeline's filters section\. |


Links don't display correctly throughout all the documents.

mmitoraj · 2023-05-08T13:55:12Z

docs/05-technical-reference/00-custom-resources/telemetry-02-logparser.md

+| **conditions**  | array | An array of conditions describing the status of the parser\. |
+| **conditions.lastTransitionTime**  | string | An array of conditions describing the status of the parser\. |
+| **conditions.reason**  | string | An array of conditions describing the status of the parser\. |
+| **conditions.type**  | string | The possible transition types are:\<br\>\- \`Running\`: The parser is ready and usable\.\<br\>\- \`Pending\`: The parser is being activated\. |


Formatting in the Description column doesn't display correctly throughout all the documents.

they can then be updated with a followup pr

kyma-bot · 2023-05-09T09:53:24Z

@k15r: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pre-main-kyma-gardener-gcp-eventing-upgrade	`2089d9f`	link	true	`/test pre-main-kyma-gardener-gcp-eventing-upgrade`

Full PR test history. Your PR dashboard.

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.

create individual tabs for API versions and separate tables for spec and

d934ddb

status

k15r requested a review from a team as a code owner April 27, 2023 16:12

kyma-bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Apr 27, 2023

update telemetry pipeline documentation

6b7fd68

k15r requested a review from a team as a code owner April 27, 2023 16:15

kyma-bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Apr 27, 2023

k15r added 4 commits April 27, 2023 18:28

add magic "open" marker to details

6b90ba9

add potentially magic blank lines

7af0f21

more magic?

723ea1c

seem tables cannot go inside divs :(

62b658e

a-thaler reviewed Apr 28, 2023

View reviewed changes

k15r closed this Apr 28, 2023

k15r added 2 commits April 28, 2023 11:43

remove leading "spec" / "status"

acad4c9

generate subscription-documentation

1fb9520

k15r reopened this Apr 28, 2023

a-thaler reviewed May 2, 2023

View reviewed changes

rewrite parsing to use some intermediate datastructures and allow for

47f26bf

templating

kyma-bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels May 3, 2023

k15r added 5 commits May 3, 2023 13:43

fill missing descriptions in case of array from child object

7ddd75b

add newline after table

c8d4bd0

emphasize Parameter

8e870ca

sort versions

2089d9f

move template to constant

378b841

k15r linked an issue May 5, 2023 that may be closed by this pull request

Allow automatic generation CRD documentation #17420

Closed

4 tasks

fix review comments

73ef700

k15r dismissed pbochynski’s stale review via 73ef700 May 8, 2023 10:02

mmitoraj reviewed May 8, 2023

View reviewed changes

mmitoraj mentioned this pull request May 8, 2023

Automate CRD documentation #17347

Closed

5 tasks

k15r added 2 commits May 8, 2023 13:40

Merge remote-tracking branch 'upstream/main' into tabs-for-crd-versions

f946791

escape markdown characters, expose required

b4b6f93

k15r requested a review from Teneroy May 8, 2023 13:02

mmitoraj reviewed May 8, 2023

View reviewed changes

Teneroy previously approved these changes May 8, 2023

View reviewed changes

kyma-bot added the lgtm Looks good to me! label May 8, 2023

dont escape the description, so that links render correctly

efe35f0

k15r dismissed Teneroy’s stale review via efe35f0 May 9, 2023 08:13

kyma-bot removed the lgtm Looks good to me! label May 9, 2023

replace type array with []object for arrays of objects

1c410f5

kyma-bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels May 9, 2023

revert all changes to actual documentation-files

ecc69eb

they can then be updated with a followup pr

kyma-bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels May 9, 2023

k15r added 2 commits May 9, 2023 12:40

update documentation using make generate

60efdb2

restore eventingbackend docu from main

f09c35b

k15r requested a review from Teneroy May 9, 2023 10:45

mmitoraj approved these changes May 9, 2023

View reviewed changes

kyma-bot assigned mmitoraj May 9, 2023

mmitoraj approved these changes May 9, 2023

View reviewed changes

kyma-bot added the lgtm Looks good to me! label May 9, 2023

pbochynski approved these changes May 9, 2023

View reviewed changes

kyma-bot merged commit 83054f4 into kyma-project:main May 9, 2023
12 checks passed

k15r added the area/documentation Issues or PRs related to documentation label May 25, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CRD documentation list all versions #17421

CRD documentation list all versions #17421

k15r commented Apr 27, 2023 •

edited

netlify bot commented Apr 27, 2023 •

edited

a-thaler Apr 28, 2023

k15r Apr 28, 2023

a-thaler commented Apr 28, 2023

k15r commented Apr 28, 2023

a-thaler May 2, 2023

a-thaler May 2, 2023

mmitoraj left a comment

mmitoraj May 8, 2023

mmitoraj May 8, 2023

mmitoraj May 8, 2023

k15r May 8, 2023

mmitoraj May 8, 2023

mmitoraj May 8, 2023

mmitoraj May 8, 2023

mmitoraj May 8, 2023

mmitoraj left a comment

mmitoraj May 8, 2023

mmitoraj May 8, 2023

kyma-bot commented May 9, 2023 •

edited

	\| sink \| string required \| Sink defines endpoint of the subscriber \|
	\| sink \| string required \| Defines the subscriber's endpoint. \|

	\| id \| string \| ID is the unique identifier of Subscription, read-only. \|
	\| id \| string \| The unique identifier of the Subscription, read-only. \|

	\| source \| string required \| Source Defines the source of the event originated from. \|
	\| source \| string required \| The origin from which events are published.\|

	\| typeMatching \| string \| TypeMatching defines the type of matching to be done for the event types. \|
	\| typeMatching \| string \| Defines the matching type for event types. \|

	\| types \| []string \| Types defines the list of event names for the topics we need to subscribe for messages. \|
	\| types \| []string \| Defines the list of event names for the topics we need to subscribe to for messages. \|

CRD documentation list all versions #17421

CRD documentation list all versions #17421

Conversation

k15r commented Apr 27, 2023 • edited

netlify bot commented Apr 27, 2023 • edited

✅ Deploy Preview for kyma-project-docs-preview ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

a-thaler commented Apr 28, 2023

k15r commented Apr 28, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mmitoraj 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mmitoraj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kyma-bot commented May 9, 2023 • edited

k15r commented Apr 27, 2023 •

edited

netlify bot commented Apr 27, 2023 •

edited

kyma-bot commented May 9, 2023 •

edited