Propose mdox for docs formatting and link checking

[saswatamcode]

Description

This PR proposes the use of mdox for formatting docs, both remote and local link checking, and for generating markdown code blocks within them.

• Removes previous docs link check CI and replaces it with mdox which would fail on broken links or incorrect markdown formatting. Also, mdox can be run locally and shows diffs so commiter can check beforehand.
• Removes embedmd and replaces it with mdox-exec code block directives which are much more customizable, as they use linux command outputs for formatting code blocks, for e.g yaml mdox-exec="cat example/storage/storageclass.yaml".
• Adds make docs and make check-docs for running mdox fmt and mdox fmt --check

This check currently skips all generated docs, as specified in cmd/po-docgen.

Doc transforming can be added later!

Note: Would need feedback on how Makefile and CI use mdox and if it can be better! 🙂

cc: @bwplotka

Type of change

What type of changes does your code introduce to the Prometheus operator? Put an x in the box that apply.

• CHANGE (fix or feature that would cause existing functionality to not work as expected)
• FEATURE (non-breaking change which adds functionality)
• BUGFIX (non-breaking change which fixes an issue)
• ENHANCEMENT (non-breaking change which improves existing functionality)
• NONE (if none of the other choices apply. Example, tooling, build system, CI, docs, etc.)

Changelog entry

Add mdox to CI for easier formatting, link checking, and generation of markdown code blocks in Documentation.

[paulfantom]

Is there no line length limit in mdox? I don't see why we would like to switch from nicely formatted multiline text to single-line one. Especially since the latter one is harder to compare when using diff.

[bwplotka]

Hm, is it really hareder to review?

Let us know if it's a blocker, we could add that feature, but it looks fine for me TBH.

[bwplotka]

Related Kunde21/markdownfmt#29

[paulfantom]

For me, yes, it is. With multi-line, GitHub would present just a small part that has changed, here it presents one giant block of changed text. I don't see why I would need to go through a 400 char paragraph to figure out the PR is just fixing a simple typo. Plus, if a paragraph is very long, GitHub will collapse file change in diff view.

[saswatamcode]

Hi @paulfantom! mdox now supports preserving soft line breaks(bwplotka/mdox#75). This PR has been updated with the same! 🙂

[paulfantom]

This is converting all nicely formatted multi-line paragraphs into single-line ones. Having text written this way will create usability issues when using diff (for example in PRs).

[bwplotka]

Yea, that's kind of a feature, you don't need multi-line in practice - all tools are wrapping lines for you, so why doing this manual work? 🤔 It's hard to edit anything.

In terms of diff, why there are usability issues? In terms of merging, you don't have correct merge options for human text anyway. 🤔

Anyway, we can add some option to wrap automatically to given length maybe, but to me there is no point ):

[bwplotka]

Nice work, love it 👍🏽

It's up to all maintainers if they want this tool here, LGTM to me. Let's make sure everyone is happy.

[bwplotka]

Hm, is it really hareder to review?

Let us know if it's a blocker, we could add that feature, but it looks fine for me TBH.

[bwplotka]

Looks like your point was addressed @paulfantom , do you think it's worth a try? (: cc @simonpasquier @fpetkovski

[paulfantom]

Sorry, I was on vacation for the last few weeks.

It looks good from my side and I would love to see this merged. Could you rebase it so merge conflicts are solved?

Thanks for all your help! 💪 👍

[saswatamcode]

@paulfantom I've rebased and updated mdox to latest. 🙂

[philipgough]

/lgtm