docs: add content tabs in code examples in reference section #3005

vishalvivekm · 2024-02-09T11:12:02Z

Description

We've a bunch of code snippets / examples on KeptnMetricsProvider and KeptnTaskDefinition CRD reference pages that are listed vertically.

This PR groups related examples in tabs as instructed in the issue.
Creates slugified anchor tags for each tab ensuring we don't have any broken reference on the page.

slugify: !!python/object/apply:pymdownx.slugs.slugify
       kwds:
         case: lower

Here's the Video Preview:
Screencast from 09-02-24 04:18:31 PM IST.webm

Fixes #2922

Checklist

My PR fulfills the Definition of Done of the corresponding issue and not more (or parts if the issue is separated
into multiple PRs)
I used descriptive commit messages to help reviewers understand my thought process
I signed off all my commits according to the Developer Certificate of Origin (DCO)
see Contribution Guide
My PR title is formatted according to the semantic PR conventions described in
the Contribution Guide
My code follows the style guidelines of this project (golangci-lint passes, YAMLLint passes)
I have performed a self-review of my code
My changes result in all-green PR checks (first-time contributors need to ask a maintainer to approve their test runs)

Signed-off-by: vishalvivekm <[email protected]>

vishalvivekm · 2024-02-09T11:26:58Z

Hi @mowies, I've made the required changes.
The spell checker actions is failing: kwds is not a recognized word.

This can probably be ignored ;)

odubajDT · 2024-02-09T11:30:20Z

Hi @mowies, I've made the required changes. The spell checker actions is failing: kwds is not a recognized word.

This can be ignored ;)

Hi @vishalvivekm thank you for contribution! :)

Please add kwds into the recognized words list. The list is present in .github/actions/spelling/expect.txt

Thank you!

Signed-off-by: vishalvivekm <[email protected]>

vishalvivekm · 2024-02-09T11:44:04Z

@mowies I've done the required changes, the Spell Checker workflow is failing though.

Hi @mowies, I've made the required changes. The spell checker actions is failing: kwds is not a recognized word.
This can be ignored ;)

Hi @vishalvivekm thank you for contribution! :)

Please add kwds into the recognized words list. The list is present in .github/actions/spelling/expect.txt

Thank you!

Thanks @odubajDT, it was helpful and all checks are passing! :)

odubajDT · 2024-02-09T11:55:15Z

@mowies I've done the required changes, the Spell Checker workflow is failing though.

Hi @mowies, I've made the required changes. The spell checker actions is failing: kwds is not a recognized word.
This can be ignored ;)

Hi @vishalvivekm thank you for contribution! :)
Please add kwds into the recognized words list. The list is present in .github/actions/spelling/expect.txt
Thank you!

Thanks @odubajDT, it was helpful and all checks are passing! :)

No problem :) Can you please have a look also on the failing yaml and markdown lint checks? Thank you!

Signed-off-by: vishalvivekm <[email protected]>

vishalvivekm · 2024-02-09T12:44:32Z

No problem :) Can you please have a look also on the failing yaml and markdown lint checks? Thank you!

Thank you! I fixed the yaml one.

For Markdown lint checks:
There are two types of issues that the action highlightes:

1. MD051/link-fragments Link fragments should be valid [Context: "[Example 3: functionRef for a python-runner runner](#example-3-functionref-for-a-python-runtime-runner)"]
  It's happening due to the changes like :

Before: ### Example 3: functionRef for a python-runtime runner
After: === "Example 3: functionRef for a python-runtime runner"

These aren't really an issue in my opinion as the extension:

  - pymdownx.tabbed:
      alternate_style: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

generates the corresponding anchor tags ( i.e. in this case example-3-functionref-for-a-python-runtime-runner) for each content tab on runtime and I've checked 'em all.

2nd type: [Expected: fenced; Actual: indented]
So for content tab, mkdocs necessarily requires same indentation for either plain text or code snippets in markdown.
Now, if we fence the plain text too, we'll lose the original formatting and it will look like this:

Ideally and ( currently in the build preview ) it looks like :

…pages Signed-off-by: vishalvivekm <[email protected]>

vishalvivekm · 2024-02-09T16:21:42Z

Given the explanation above, I think it makes sense to go ahead and disable these specific markdown lint checks in the sections of the two pages, where changes are made.

[MD051] link-fragments - Link fragments should be valid
[MD046] code-block-style - Code block style

docs/docs/reference/crd-reference/taskdefinition.md

Signed-off-by: vishalvivekm <[email protected]>

docs/docs/reference/crd-reference/metricsprovider.md

StackScribe

Nice job on the coding! Now comes the question of how the examples should be arranged on the page. Right now, this gives us all the examples for each runner in one section, which is how the page was arranged. But there is some sentiment to group the examples by functionality with tabs for each runner.

I think we should merge this PR using the existing structure then have a separate issue that we can discuss and then implement in a new PR if we want to restructure the content.

Signed-off-by: Vivek Vishal <[email protected]>

Signed-off-by: vishalvivekm <[email protected]>

docs/docs/reference/crd-reference/taskdefinition.md

docs/docs/assets/crd/examples/synopsis-for-container-runtime.yaml

odubajDT · 2024-02-19T07:10:04Z

Please let's try to fix the MD linter errors. Here are the logs from the test

docs/docs/reference/crd-reference/taskdefinition.md:38:1 MD007/ul-indent Unordered list indentation [Expected: 4; Actual: 2]
docs/docs/reference/crd-reference/taskdefinition.md:47:5 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:50:1 MD007/ul-indent Unordered list indentation [Expected: 4; Actual: 2]
docs/docs/reference/crd-reference/taskdefinition.md:54:5 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:92:11 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:96:11 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:209:23 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:212:121 MD013/line-length Line length [Expected: 120; Actual: 137]
docs/docs/reference/crd-reference/taskdefinition.md:212:23 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:228:23 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:230:23 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:257:23 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:259:121 MD013/line-length Line length [Expected: 120; Actual: 137]
docs/docs/reference/crd-reference/taskdefinition.md:259:23 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:265:23 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:267:121 MD013/line-length Line length [Expected: 120; Actual: 139]
docs/docs/reference/crd-reference/taskdefinition.md:267:23 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:280:19 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:282:121 MD013/line-length Line length [Expected: 120; Actual: 132]
docs/docs/reference/crd-reference/taskdefinition.md:282:19 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:297:19 MD033/no-inline-html Inline HTML [Element: a]
docs/docs/reference/crd-reference/taskdefinition.md:299:121 MD013/line-length Line length [Expected: 120; Actual: 132]
docs/docs/reference/crd-reference/taskdefinition.md:299:19 MD033/no-inline-html Inline HTML [Element: a]

vishalvivekm · 2024-02-19T09:06:20Z

MD033/no-inline-html Inline HTML [Element: a]

Hi, to avoid the MD051( why is this happening I've explained in this comment: #3005 (comment) ):

MD051/link-fragments Link fragments should be valid 
[Context: "[Example 3: functionRef for a python-runner runner](#example-3-functionref-for-a-python-runtime-runner)"]

I've used html anchor tags like this:

<a href="#example-3-functionref-for-a-python-runtime-runner">Example 3: functionRef for a python-runtime runner</a>

which is now causing MD033/no-inline-html Inline HTML [Element: a] and at some places: MD013/line-length Line length as the elements have length >= 120 .
We'll have to allow <a> in the markdown, can I disable these linters for the anchor tags in the page using  syntax, @odubajDT ?

Signed-off-by: vishalvivekm <[email protected]>

odubajDT · 2024-02-19T09:27:15Z

MD033/no-inline-html Inline HTML [Element: a]

Hi, to avoid the MD051( why is this happening I've explained in this comment: #3005 (comment) ):
MD051/link-fragments Link fragments should be valid 
[Context: "[Example 3: functionRef for a python-runner runner](#example-3-functionref-for-a-python-runtime-runner)"]
I've used html anchor tags like this:
<a href="#example-3-functionref-for-a-python-runtime-runner">Example 3: functionRef for a python-runtime runner</a>
which is now causing MD033/no-inline-html Inline HTML [Element: a] and at some places: MD013/line-length Line length as the elements have length >= 120 . We'll have to allow <a> in the markdown, can I disable these linters for the anchor tags in the page using  syntax, @odubajDT ?

@vishalvivekm let's try to add the element to the list of allowed elements here and see if it works for our use-case.

Regarding the line length, it should be ok to disable the line-length markdownlint check but only for that particular lines. Let's please not do that for bigger blocks.

…sing include Signed-off-by: vishalvivekm <[email protected]>

Signed-off-by: vishalvivekm <[email protected]>

codecov · 2024-02-19T09:49:58Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (ce57993) 85.75% compared to head (c5006e6) 86.77%.
Report is 47 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3005      +/-   ##
==========================================
+ Coverage   85.75%   86.77%   +1.02%     
==========================================
  Files         162      162              
  Lines       10351     8554    -1797     
==========================================
- Hits         8876     7423    -1453     
+ Misses       1186      841     -345     
- Partials      289      290       +1

see 141 files with indirect coverage changes

Flag	Coverage Δ
certificate-operator	`69.23% <ø> (+1.80%)`	⬆️
component-tests	`56.64% <ø> (+0.64%)`	⬆️
keptn-lifecycle-operator	`?`
lifecycle-operator	`86.40% <ø> (+1.11%)`	⬆️
metrics-operator	`88.32% <ø> (+0.68%)`	⬆️
scheduler	`34.74% <ø> (-1.79%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

vishalvivekm · 2024-02-19T09:52:22Z

All done @odubajDT

odubajDT

Thank you for your contribution!

vishalvivekm · 2024-02-19T09:56:01Z

Thank you for your contribution!

😄
Thanks to you too, for offering your help and additional resources 😎

RealAnna

@vishalvivekm this looks already so much better 🚀 ! I was wondering if it makes sense to tab by example instead of by runtime. Most of the example use cases are present for both runtimes, and I think that would be an easier way to see each possible configuration...

eg.

Inline ex (both python and deno)
Httpref ex (both)

and so on...

It is a bit difficult to search the page for specific examples right now

vishalvivekm · 2024-02-19T10:36:31Z

@vishalvivekm this looks already so much better 🚀 ! I was wondering if it makes sense to tab by example instead of by runtime. Most of the example use cases are present for both runtimes, and I think that would be an easier way to see each possible configuration...

eg.

Inline ex (both python and deno) Httpref ex (both)

and so on...

It is a bit difficult to search the page for specific examples right now

Makes sense @RealAnna , thank you for the review.
I'll go ahead and make changes.

Signed-off-by: vishalvivekm <[email protected]>

vishalvivekm · 2024-02-19T11:08:25Z

@vishalvivekm this looks already so much better 🚀 ! I was wondering if it makes sense to tab by example instead of by runtime. Most of the example use cases are present for both runtimes, and I think that would be an easier way to see each possible configuration...
eg.
Inline ex (both python and deno) Httpref ex (both)
and so on...
It is a bit difficult to search the page for specific examples right now

Makes sense @RealAnna , thank you for the review. I'll go ahead and make changes.

done ✔️

docs/docs/reference/crd-reference/taskdefinition.md

Signed-off-by: vishalvivekm <[email protected]>

sonarqubecloud · 2024-02-19T15:00:25Z

Quality Gate passed

Issues
0 New issues

Measures
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud

RealAnna

very nice 🚀 💪 🎊

docs/docs/reference/crd-reference/taskdefinition.md

) Signed-off-by: vishalvivekm <[email protected]> Signed-off-by: Vivek Vishal <[email protected]> Signed-off-by: shivam <[email protected]>

) Signed-off-by: vishalvivekm <[email protected]> Signed-off-by: Vivek Vishal <[email protected]> Signed-off-by: vickysomtee <[email protected]>

vishalvivekm added 3 commits February 9, 2024 16:10

add-extensions-config

ff098fd

Signed-off-by: vishalvivekm <[email protected]>

feat: add tabs in KeptnMetricsProvider page

70b8f98

Signed-off-by: vishalvivekm <[email protected]>

feat: add tabs in KeptnTaskDefinition page

d65db3a

Signed-off-by: vishalvivekm <[email protected]>

vishalvivekm requested review from a team as code owners February 9, 2024 11:12

github-actions bot added the documentation Improvements or additions to documentation label Feb 9, 2024

Merge branch 'main' into main

a605fdc

vishalvivekm changed the title ~~add-content-tabs-in-code-examples-in-reference-section~~ feat: add-content-tabs-in-code-examples-in-reference-section Feb 9, 2024

chore: add kwds in expected words list

5980591

Signed-off-by: vishalvivekm <[email protected]>

github-actions bot added the ops label Feb 9, 2024

chore: fix failing YAML checks

bddaad6

Signed-off-by: vishalvivekm <[email protected]>

chore: disable MD046 and MD051 for content tabs on the two reference …

2525588

…pages Signed-off-by: vishalvivekm <[email protected]>

odubajDT reviewed Feb 10, 2024

View reviewed changes

docs/docs/reference/crd-reference/taskdefinition.md Show resolved Hide resolved

vishalvivekm added 2 commits February 11, 2024 01:05

chore: move code examples to seperate files to be referenced via include

5efb09b

Signed-off-by: vishalvivekm <[email protected]>

chore: add newline at the end of yaml files to fix the yaml check

381be2d

Signed-off-by: vishalvivekm <[email protected]>

odubajDT reviewed Feb 11, 2024

View reviewed changes

docs/docs/reference/crd-reference/metricsprovider.md Show resolved Hide resolved

odubajDT reviewed Feb 11, 2024

View reviewed changes

docs/docs/reference/crd-reference/metricsprovider.md Show resolved Hide resolved

odubajDT changed the title ~~feat: add-content-tabs-in-code-examples-in-reference-section~~ docs: add content tabs in code examples in reference section Feb 11, 2024

StackScribe reviewed Feb 12, 2024

View reviewed changes

StackScribe mentioned this pull request Feb 12, 2024

docs: fix formatting for KeptnTaskDefinition crd-ref #3016

Merged

vishalvivekm and others added 2 commits February 14, 2024 19:44

Merge branch 'main' into main

e313294

Signed-off-by: Vivek Vishal <[email protected]>

chore: remove the MD051 ignorer from metricsprovider page

2c743fb

Signed-off-by: vishalvivekm <[email protected]>

odubajDT reviewed Feb 14, 2024

View reviewed changes

docs/docs/reference/crd-reference/taskdefinition.md Outdated Show resolved Hide resolved

odubajDT reviewed Feb 14, 2024

View reviewed changes

docs/docs/reference/crd-reference/taskdefinition.md Outdated Show resolved Hide resolved

odubajDT reviewed Feb 19, 2024

View reviewed changes

docs/docs/assets/crd/examples/synopsis-for-container-runtime.yaml Outdated Show resolved Hide resolved

chore: add newline and required indentation

3b01f4a

Signed-off-by: vishalvivekm <[email protected]>

vishalvivekm added 3 commits February 19, 2024 14:58

chore: move remaining snippets to seperate files and reference them u…

71defda

…sing include Signed-off-by: vishalvivekm <[email protected]>

chore: add a to allowed inline elments

77df8cd

Signed-off-by: vishalvivekm <[email protected]>

chore: disable MD013 linter for only required anchor tags

114323c

Signed-off-by: vishalvivekm <[email protected]>

odubajDT previously approved these changes Feb 19, 2024

View reviewed changes

RealAnna requested changes Feb 19, 2024

View reviewed changes

chore: group tabs by example for both the runtimes together

dd6cf45

Signed-off-by: vishalvivekm <[email protected]>

vishalvivekm dismissed odubajDT’s stale review via dd6cf45 February 19, 2024 10:58

chore: fix markdown check actions/runs/7958452671/job/21723348299

4940644

Signed-off-by: vishalvivekm <[email protected]>

RealAnna reviewed Feb 19, 2024

View reviewed changes

docs/docs/reference/crd-reference/taskdefinition.md Outdated Show resolved Hide resolved

vishalvivekm added 2 commits February 19, 2024 20:20

chore: remove-cofigMap-from-httpRef-example-for-python-runtime

0d1c48a

Signed-off-by: vishalvivekm <[email protected]>

chore: add MD033 ignorer for adding br element

c5006e6

Signed-off-by: vishalvivekm <[email protected]>

RealAnna approved these changes Feb 19, 2024

View reviewed changes

odubajDT reviewed Feb 19, 2024

View reviewed changes

docs/docs/reference/crd-reference/taskdefinition.md Show resolved Hide resolved

RealAnna approved these changes Feb 20, 2024

View reviewed changes

odubajDT approved these changes Feb 20, 2024

View reviewed changes

odubajDT merged commit cf0c170 into keptn:main Feb 20, 2024
34 checks passed

keptn-bot mentioned this pull request Feb 20, 2024

chore: release keptn 2.0.0-rc.1 #2997

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add content tabs in code examples in reference section #3005

docs: add content tabs in code examples in reference section #3005

vishalvivekm commented Feb 9, 2024 •

edited

Loading

vishalvivekm commented Feb 9, 2024 •

edited

Loading

odubajDT commented Feb 9, 2024

vishalvivekm commented Feb 9, 2024

odubajDT commented Feb 9, 2024

vishalvivekm commented Feb 9, 2024 •

edited

Loading

vishalvivekm commented Feb 9, 2024

StackScribe left a comment

odubajDT commented Feb 19, 2024

vishalvivekm commented Feb 19, 2024

odubajDT commented Feb 19, 2024

codecov bot commented Feb 19, 2024 •

edited

Loading

vishalvivekm commented Feb 19, 2024

odubajDT left a comment

vishalvivekm commented Feb 19, 2024

RealAnna left a comment

vishalvivekm commented Feb 19, 2024

vishalvivekm commented Feb 19, 2024

sonarqubecloud bot commented Feb 19, 2024

RealAnna left a comment

docs: add content tabs in code examples in reference section #3005

docs: add content tabs in code examples in reference section #3005

Conversation

vishalvivekm commented Feb 9, 2024 • edited Loading

Description

Checklist

vishalvivekm commented Feb 9, 2024 • edited Loading

odubajDT commented Feb 9, 2024

vishalvivekm commented Feb 9, 2024

odubajDT commented Feb 9, 2024

vishalvivekm commented Feb 9, 2024 • edited Loading

vishalvivekm commented Feb 9, 2024

StackScribe left a comment

Choose a reason for hiding this comment

odubajDT commented Feb 19, 2024

vishalvivekm commented Feb 19, 2024

odubajDT commented Feb 19, 2024

codecov bot commented Feb 19, 2024 • edited Loading

Codecov Report

vishalvivekm commented Feb 19, 2024

odubajDT left a comment

Choose a reason for hiding this comment

vishalvivekm commented Feb 19, 2024

RealAnna left a comment

Choose a reason for hiding this comment

vishalvivekm commented Feb 19, 2024

vishalvivekm commented Feb 19, 2024

sonarqubecloud bot commented Feb 19, 2024

Quality Gate passed

RealAnna left a comment

Choose a reason for hiding this comment

vishalvivekm commented Feb 9, 2024 •

edited

Loading

vishalvivekm commented Feb 9, 2024 •

edited

Loading

vishalvivekm commented Feb 9, 2024 •

edited

Loading

codecov bot commented Feb 19, 2024 •

edited

Loading