Skip to content
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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

wenzeslaus
Copy link
Member

@wenzeslaus wenzeslaus commented Mar 6, 2025

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.

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.
@github-actions github-actions bot added GUI wxGUI related Python Related code is in Python C Related code is in C libraries docs markdown Related to markdown, markdown files labels Mar 6, 2025
@wenzeslaus
Copy link
Member Author

@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:

  1. docs: Use YAML list for keywords in front matter #5320 (first, this repo)
  2. docs: Use YAML list for keywords in front matter grass-addons#1357 (second, grass-addons repo)
  3. docs: Use keywords property in MkDocs, not separate tags #5318 (third, this PR)

@wenzeslaus wenzeslaus self-assigned this Mar 6, 2025
@echoix
Copy link
Member

echoix commented Mar 7, 2025

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

petrasovaa pushed a commit that referenced this pull request Mar 7, 2025
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.
@wenzeslaus
Copy link
Member Author

...It isn't a day to day thing to have interdependent PRs like this. And having dependencies between repos doesn't help either

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.

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).

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.

@wenzeslaus wenzeslaus enabled auto-merge (squash) March 7, 2025 16:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C Related code is in C docs GUI wxGUI related libraries markdown Related to markdown, markdown files Python Related code is in Python
Projects
Status: In Progress
Development

Successfully merging this pull request may close these issues.

2 participants