DOCS-1007: Create sync pattern to pull in the CRD during releases

[ravindk89]

Summary

Closes #1007

Staged: http://192.241.195.202:9000/staging/DOCS-1007/k8s/reference/operator-crd.html

This PR is a bit of an automation trick for us to lean on. Effectively it adds one new Makefile command we can run at any time.

It pulls down the https://github.com/minio/operator/blob/v5.0.9/docs/tenant_crd.adoc using the latest available release tag, processes it through a combination of asciidoc and pandoc, and then does some sed magic to clean up the TOC to be more navigable.

This requires installation of asciidoc and pandoc to run. It will, for now, be a manual process we run when Operator releases get generated. It should simply overwrite the includes/k8s/ext-tentant-crd.md file with the newly updated content.

How to test

Install asciidoc and pandoc

Run make sync-operator-crd

It should work

Not in scope

Styling the tables - although interestingly this markdown table does breaks on long monospaced texts. @rushenn if you can see what style trick is applied here, and if we apply that to other tables in general, it might fix a bit of a css pain point we've had.

[feorlen]

I'm kinda fuzzy about the process.

Asciidoc docs say it's a markup language, not a software package, and install asciidoctor instead. So:

$ brew install pandoc
$ brew install asciidoctor
$ make sync-operator-crd
./sync-minio-operator-crd.sh: line 8: asciidoc: command not found
Invalid XML:
Missing root element
make: *** [sync-operator-crd] Error 44

But this installs:

$ brew install asciidoc
$ make sync-operator-crd
asciidoc: WARNING: <stdin>: line 49: no output from filter: "/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/bin/python3.11" -m "asciidoc" -b docbook45  --attribute "anchor_prefix=k8s-api" -a "indir=/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/lib/python3.11/site-packages/asciidoc/resources" -a "blockname=table" -s -
asciidoc: WARNING: <stdin>: line 372: no output from filter: "/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/bin/python3.11" -m "asciidoc" -b docbook45  --attribute "anchor_prefix=k8s-api" -a "indir=/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/lib/python3.11/site-packages/asciidoc/resources" -a "blockname=table" -s -
asciidoc: WARNING: <stdin>: line 495: no output from filter: "/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/bin/python3.11" -m "asciidoc" -b docbook45  --attribute "anchor_prefix=k8s-api" -a "indir=/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/lib/python3.11/site-packages/asciidoc/resources" -a "blockname=table" -s -
asciidoc: WARNING: <stdin>: line 595: no output from filter: "/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/bin/python3.11" -m "asciidoc" -b docbook45  --attribute "anchor_prefix=k8s-api" -a "indir=/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/lib/python3.11/site-packages/asciidoc/resources" -a "blockname=table" -s -
sed: 1: "source/includes/k8s/ext ...": unterminated substitute pattern
make: *** [sync-operator-crd] Error 1

It did something, at least

-rw-r--r--  1 andrealongo  staff  61255 Oct  5 14:19 ext-tenant-crd.md

-rw-r--r--  1 andrealongo  staff  61243 Oct  5 14:32 ext-tenant-crd.md

[feorlen]

Links don't do anything, there are supposed to be anchors in the page?
md

-   [Tenant](#k8s-api-github-com-minio-operator-pkg-apis-minio-min-io-v2-tenant)

url

file:///Users/andrealongo/repos/docs/build/DOCS-1007/k8s/html/reference/operator-crd.html#k8s-api-github-com-minio-operator-pkg-apis-minio-min-io-v2-tenant

[ravindk89]

OK the SED issue I think I know is because of a difference between gnu and bash sed. I can fix that

As far as the links...those are probably irrevocably broken. Maybe. I might be able to wildcard-sed through them though. Will take a shot.

[feorlen]

👍🏻 Lemme know when you want another test

[ravindk89]

I'll have to poke this for a bit - probably tomorrow or early next week.

[ravindk89]

@feorlen @djwfyi can you test the scripts again? I added logic that may work on Darwin

[feorlen]

Were the links expected to work this time, or no?

I'm not getting the sed error anymore, but I still get the asciidoc warnings. Is there something I can collect from my local for you to examine?

[djwfyi]

Similar to Andrea, I'm getting the following:

(venv) ➜  baremetal git:(DOCS-1007) make sync-operator-crd
asciidoc: WARNING: <stdin>: line 49: no output from filter: "/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/bin/python3.11" -m "asciidoc" -b docbook45  --attribute "anchor_prefix=k8s-api" -a "indir=/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/lib/python3.11/site-packages/asciidoc/resources" -a "blockname=table" -s -
asciidoc: WARNING: <stdin>: line 372: no output from filter: "/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/bin/python3.11" -m "asciidoc" -b docbook45  --attribute "anchor_prefix=k8s-api" -a "indir=/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/lib/python3.11/site-packages/asciidoc/resources" -a "blockname=table" -s -
asciidoc: WARNING: <stdin>: line 495: no output from filter: "/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/bin/python3.11" -m "asciidoc" -b docbook45  --attribute "anchor_prefix=k8s-api" -a "indir=/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/lib/python3.11/site-packages/asciidoc/resources" -a "blockname=table" -s -
asciidoc: WARNING: <stdin>: line 595: no output from filter: "/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/bin/python3.11" -m "asciidoc" -b docbook45  --attribute "anchor_prefix=k8s-api" -a "indir=/opt/homebrew/Cellar/asciidoc/10.2.0/libexec/lib/python3.11/site-packages/asciidoc/resources" -a "blockname=table" -s -

[ravindk89]

OK - I get the same warnings, and as I can tell it doesn't break the build. I'm also not sure where it's originating from or how to fix them.

They might be stuff we have to live with - if it's annoying I'll see if there's a way to suppress the output.

[feorlen]

Is it otherwise producing the expected output for you? I'm not sure if this was supposed to have something in the second column. Do we need to manually fix links when using this?

[ravindk89]

@feorlen I think that's actually a CSS issue - it's Field : Description, but you can't read any of it due to the CSS applied. I can try to hack a fix into this...

[djwfyi]

That particular example, the second column is blank for all three rows.
@feorlen @ravindk89

All of the problem lines are the table closings lines. But it's only on certain tables. I'm seeing if I can figure out what the parser is having issues with.

[djwfyi]

Oh, duh, the header row is, in fact, problematic.

The parser is having issues with any table that has one or more blank cells.

[feorlen]

with 3rd commit, much better

[djwfyi]

Update the README, please.
Need to update Sphinx version (we are on 6.x.x now) and add in Pandoc/Asciidoc and prereqs.

[feorlen]

👍🏻