Adding feature stability table to docs and including one example for encryption support in cilium

[moshevayner]

Fixes #9151
To get started, I also added this table to the cilium docs for a feature I previously added. This can provide an example for additional features to which we would like to add this table.
Example output of the table when rendered:

/cc @rifelpet @olemarkus

[moshevayner]

I might be missing something, but following the failure output of hack/verify-boilerplate.sh I ran hack/update-header.sh but nothing happens, it doesn't seem to change anything in mkdocs_macro.py.
If I read that script correctly, I think it looks for the copyright block, so I tried adding that manually and it still didn't work.

What am I missing?

mosheshitrit:kops mosheshitrit$ hack/verify-boilerplate.sh
FAIL: Boilerplate header is wrong for: /Users/mosheshitrit/src/kubernetes/kops/src/k8s.io/kops/mkdocs_macros.py
FAIL: Please execute ./hack/update-header.sh
mosheshitrit:kops mosheshitrit$ hack/update-header.sh
mosheshitrit:kops mosheshitrit$ hack/verify-boilerplate.sh
FAIL: Boilerplate header is wrong for: /Users/mosheshitrit/src/kubernetes/kops/src/k8s.io/kops/mkdocs_macros.py
FAIL: Please execute ./hack/update-header.sh

[moshevayner]

OK found it.
Apparently hack/update_header.sh doesn't have a config for .py files even though it does exist under hack/boilerplate folder. Adding a commit to address that.

[olemarkus]

/lgtm

Why did the netlify deploy cancel though?

[hakman]

Why did the netlify deploy cancel though?

@olemarkus Most likely because last commit was on a something not tracked by config file:

kops/netlify.toml

Line 5 in 8c3b4e4

ignore = "git diff --quiet HEAD^ HEAD netlify.toml Makefile mkdocs.yml docs/ images/"

@MoShitrit any chance mkdocs_macros.py can be moved to the scripts dir?

[moshevayner]

Why did the netlify deploy cancel though?

@olemarkus Most likely because last commit was on a something not tracked by config file:

kops/netlify.toml

Line 5 in 8c3b4e4

ignore = "git diff --quiet HEAD^ HEAD netlify.toml Makefile mkdocs.yml docs/ images/"

@MoShitrit any chance mkdocs_macros.py can be moved to the scripts dir?

@hakman Yeah, sure. I think it'll involve some additional config to the plugin but I can do that.
By the scripts dir- do you mean I should create one and put it there? Or is it the hack dir?
I tried to find a dir named scripts but couldn't find any.

[hakman]

@MoShitrit you are right, meant hack. Thanks!

[moshevayner]

@hakman
Okay, so after re-reading their docs about the location of the module, I think it might work out better to have a dedicated python package under the root directory, if we don't want to have the file located in the same path as mkdocs.yml. So I'm thinking probably creating a python package called mkdocs_macros/ and moving the .py file to this folder. Then we'll have to change the plugin config to point to that directory and that should do it.
WDYT? Is it worth the effort? Or should we just keep it as it is now?
If we do want to use the hack dir, we'll have to convert it to a python package (by adding a __init__.py file as well there. I'm okay with taking that approach as well, but I'm not sure if we should do it, since most of the files there aren't python and aren't really used by mkdocs at all.

[hakman]

Thanks for checking @MoShitrit . I don't think it's worth the extra work, but let's see if @rifelpet and @mikesplain have some feedback also.

[rifelpet]

I think I'd lean towards moving mkdocs_macros.py into the hack directory and add a hack/__init__.py that way we avoid yet another file in the repo root. I think if you squash your commits, the netlify job will not be cancelled and we'll be able to check it out in the browser.

[moshevayner]

Created a new package under hack called mkdocs_macros and updated mkdocs.yml to point to the new package as the module for Mkdocs-macros plugin.
I see that the netlify deploy preview worked this time, so we can see an example of the table here

[mikesplain]

This looks great, thanks so much for your work on this @MoShitrit!

My only comment is more of a nit, looks like the table goes full with rather than ending at the second column. Any way we can clean this up?

Other than that, I think this is a great start!

[moshevayner]

Thanks, @mikesplain !
So I tried to look into that table alignment/padding thing, but I think it's more of how Mkdocs renders every custom block (tables, code etc.). I have a strong feeling this comes from the Mkdocs-material theme we're using.
I confirmed that by finding another table in our docs which doesn't use the macros plugin at all, and it looks exactly the same - https://kops.sigs.k8s.io/welcome/releases/#compatibility-matrix
I tried to do some html styling to change that, but it kinda broke it. 😖
I tried to look a little bit a the material theme docs but couldn't find a straightforward answer on how to change that (we can maybe apply some external css, but I feel like it could be a little bit out of scope for this PR and it could take me good bit of time to figure this out, lol)
WDYT?

[mikesplain]

Hmm gotcha, you should be able to change max-width: 100%; to max-width: fit-content; on the table object, which worked for me at least. You would likely need to wrap the table in a div with a new class like class=kops_feature_table, then add an override css to extra.css like

.kops_feature_table table {
    max-width: fit-content;
}

But to your point, this is easily fixed in a separate PR if someone spends the time on it. I'm fine without it for now. Thanks for the hard work on this, it's great!

[moshevayner]

Hmm gotcha, you should be able to change max-width: 100%; to max-width: fit-content; on the table object, which worked for me at least. You would likely need to wrap the table in a div with a new class like class=kops_feature_table, then add an override css to extra.css like

.kops_feature_table table {
    max-width: fit-content;
}

But to your point, this is easily fixed in a separate PR if someone spends the time on it. I'm fine without it for now. Thanks for the hard work on this, it's great!

Yas!!! Got it now. I had to do it with a subclass, but your pointer took me to where I needed 😄

Pushing up the commit now so you can see the code change.

Thanks for that, @mikesplain ! 🙇‍♂️

[moshevayner]

Updated example with the fixed table width: https://deploy-preview-9555--kubernetes-kops.netlify.app/networking/cilium/#enabling-encryption-in-cilium

[moshevayner]

Looking to get a 👍 whenever anyone has a free cycle
@mikesplain @rifelpet

[hakman]

@MoShitrit could you also add the hack/ dir to this list to trigger docs updates on modules changes?

kops/netlify.toml

Line 5 in 8c3b4e4

ignore = "git diff --quiet HEAD^ HEAD netlify.toml Makefile mkdocs.yml docs/ images/"

[moshevayner]

@hakman done! 🚀 😄 d43c9b5

[hakman]

/lgtm

[moshevayner]

/retest

[rifelpet]

looks great, thanks again! hopefully we can get this setup with all the other feature docs too.

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: MoShitrit, rifelpet

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 [rifelpet]

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