-
-
Notifications
You must be signed in to change notification settings - Fork 344
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Use keywords property in MkDocs, not separate tags #5318
base: main
Are you sure you want to change the base?
Conversation
Use the keywords front matter property named after keywords of a tool (and used by the custom keywords mechanism), not an additional tags property. This means that keywords property needs to be proper YAML list, not a plain comma-separated list as a string. This is how keywords are now genered. The custom keyword parsing now accepts both version (with and without []). This does not include any keywords entered manually to Markdown because there are none in this repo, but they are in grass-addons repo which will break the MkDocs reading of the tags from the keywords property (for r.pi, r.green). This includes cleanup of keywords tool metadata syntax which is supposed to use multiple keyword keys now rather than keywords (for a single keyword). For the tags page generated by MkDocs, this adds an exclude of keyword 'unit test' which does not need to appear in the documentation.
@echoix This PR and its friends shows what I don't particularly like about our setup. I need 3 PRs instead of one or two to get the CI running. I was originally thinking I can do it with two, but I would need to do it when no one else is merging, and that would be tricky, so I did the third PR anyway. They need to go in order:
|
I don't understand well what you want me to act on, or think about. We always have an escape door for unusual situations (merging by bypassing status check requirements). It isn't a day to day thing to have interdependent PRs like this. And having dependencies between repos doesn't help either |
To use the keywords directly in MkDocs, keywords property needs to be proper YAML list, not a plain comma-separated list as a string. The keywords are now generated like that, and the custom keyword parsing now accepts both version (with and without []). This does not include any keywords entered manually to Markdown because there are none in this repo, but they are in grass-addons repo which will break the MkDocs reading of the tags from the keywords property (for r.pi, r.green). Addons are addressed in OSGeo/grass-addons#1357. This includes cleanup of keywords tool metadata syntax which is supposed to use multiple keyword keys now rather than keywords (for a single keyword). For the tags page generated by MkDocs, this adds an exclude of keyword 'unit test' which does not need to appear in the documentation. This covers only the YAML changes for keywords. The MkDocs change for tags to keywords is in #5318.
Right, that's my point. Building of addons increased the possibility of interdependent PRs. I'm not comfortable with that, but I also don't know how to avoid it.
This example is to explain what I meant when I said I'm more nervous about dependencies rather than CI time in relation to frequency of changes in the repos. |
In MkDocs, use the keywords front matter property keywords, named after keywords of a tool (and used by the custom keywords mechanism), not an additional tags property which had to be emitted by parser. This only works when the keywords property is a proper YAML list, not a plain comma-separated list as a string (which is true with 08286fb).
Original description:
Use the keywords front matter property named after keywords of a tool (and used by the custom keywords mechanism), not an additional tags property. This means that keywords property needs to be proper YAML list, not a plain comma-separated list as a string. This is how keywords are now genered. The custom keyword parsing now accepts both version (with and without []).
This does not include any keywords entered manually to Markdown because there are none in this repo, but they are in grass-addons repo which will break the MkDocs reading of the tags from the keywords property (for r.pi, r.green).
This includes cleanup of keywords tool metadata syntax which is supposed to use multiple keyword keys now rather than keywords (for a single keyword).
For the tags page generated by MkDocs, this adds an exclude of keyword 'unit test' which does not need to appear in the documentation.