[CI:DOCS] markdown-preprocess: cross-reference where opts are used#16240
Conversation
In each options/foo.md, keep a list of where the option is used. This will be valuable to anyone making future edits, and to those reviewing those edits. This may be a controversial commit, because those crossref lists are autogenerated as a side effect of the script that reads them. It definitely violates POLA. And one day, some kind person will reconcile (e.g.) --label, using it in more man pages, and maybe forget to git-commit the rewritten file, and CI will fail. I think this is a tough tradeoff, but worth doing. Without this, it's much too easy for someone to change an option file in a way that renders it inapplicable/misleading for some podman commands. Signed-off-by: Ed Santiago <santiago@redhat.com>
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: edsantiago The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
Luap99
left a comment
There was a problem hiding this comment.
I like this idea, this should also help reviewers.
| # Compare files; only rewrite if the new one differs | ||
| if not filecmp.cmp(optionfile, tmpfile): | ||
| os.rename(tmpfile, optionfile) |
There was a problem hiding this comment.
Why this extra check? Can't we just rename always?
There was a problem hiding this comment.
It's just a habit of mine: ls -lt | head -20 is easily in my top ten most frequent commands list (aliased, of course). It's incredibly useful for investigating all sorts of failures and problems and changes. So I'm always careful not to pollute directories with unnecessary mtime changes.
|
/lgtm |
In each options/foo.md, keep a list of where the option is used.
This will be valuable to anyone making future edits, and to
those reviewing those edits.
This may be a controversial commit, because those crossref lists
are autogenerated as a side effect of the script that reads them.
It definitely violates POLA. And one day, some kind person will
reconcile (e.g.) --label, using it in more man pages, and maybe
forget to git-commit the rewritten file, and CI will fail.
I think this is a tough tradeoff, but worth doing. Without this,
it's much too easy for someone to change an option file in a way
that renders it inapplicable/misleading for some podman commands.
Signed-off-by: Ed Santiago santiago@redhat.com