-
-
Notifications
You must be signed in to change notification settings - Fork 350
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: Replace keywords index by MkDocs tags #5446
docs: Replace keywords index by MkDocs tags #5446
Conversation
This removes custom keywords index and replaces the keywords.html page by a MkDocs tags listing. The default MkDocs tag anchor contains tag: prefix to help distinguishing tag headings from others, but we likely won't have a heading of the same name on the same page. However, we were using anchors without any prefix, so this will make most of the anchor links work (if there are any external ones anywhere). It also makes the anchor little simple to read and write if managed manually for any reason. The check for anchor existence is done by MkDocs before the tags page is generated. This creates false positive for the Keywords section (to be removed) and for topics. To avoid this warning for topics, and perhaps to be little more helpful, instead of linking to the keyword, this new code uses MkDocs tags listing to list pages with that keyword right on the topic page. This disables custom keywords build and disables the addons keyword integration in the CI workflow. The Python code to generate the keywords in Markdown is still in place, but it can be removed in the future possibly together with the custom HTML code (they are mixed togeher).
I'd either have the tools under each keyword be comma separated (as it used to be) to avoid an endless keywords page or add the short description to each tool to use the currently white space. |
I added description for each tool and made the tool name in cursive which we tend to use in the doc. This provides details for each tool without need to visit the link. It is long and some descriptions are long, so even one keyword section can substantial, but it somewhat mirrors the format of the other tool listings which include descriptions. (Full and category index pages have descriptions, but currently use a table, no cursive, and don't repeat the listed tools.) In the current colorsA possible style with green links(not part of this PR) |
This looks great! |
The additional change in OSGeo#5446 adding tag listing for topic pages turned out to be harmful as it makes the tags (aka keywords) on top of pages link to the tag heading in the topic pages if the listing exists. While this sort of looks like the original custom HTML behavior of second keyword being a tag, this creates inconsitency with an seemingly arbitrary keyword (not just the second or 'topic' keyword) linking to a different page than the list of keywords, but not even to the topic page itself, but to a heading inside the page because instead of a a topic, the link goes to the keyword (tag) in the listing. This preserves the additional list of tools for topic pages introduced in OSGeo#5446 by creating another instance of the material tags plugin in MkDocs using the same front matter metadata item, but different listing directive name and disabling tags for pages. This introduces a second independent tag system so keywords and topics don't mix. This is still easy to remove or modify if we decide to change or remove topics in the future.
The additional change in #5446 adding tag listing for topic pages turned out to be harmful as it makes the tags (aka keywords) on top of pages link to the tag heading in the topic pages if the listing exists. While this sort of looks like the original custom HTML behavior of second keyword being a tag, this creates inconsistency with an seemingly arbitrary keyword (not just the second or 'topic' keyword) linking to a different page than the list of keywords, but not even to the topic page itself, but to a heading inside the page because instead of a a topic, the link goes to the keyword (tag) in the listing. This preserves the additional list of tools for topic pages introduced in #5446 by creating another instance of the material tags plugin in MkDocs using the same front matter metadata item, but different listing directive name and disabling tags for pages. This introduces a second independent tag system so keywords and topics don't mix. This is still easy to remove or modify if we decide to change or remove topics in the future. The display link would go to the display topic page while general would go to keywords. Now both go to keywords.
This removes custom keywords index and replaces the keywords.html page by a MkDocs tags listing.
The default MkDocs tag anchor contains tag: prefix to help distinguishing tag headings from others, but we likely won't have a heading of the same name on the same page. However, we were using anchors without any prefix, so this will make most of the anchor links work (if there are any external ones anywhere). It also makes the anchor little simple to read and write if managed manually for any reason.
The check for anchor existence is done by MkDocs before the tags page is generated. This creates false positive for the Keywords section (to be removed) and for topics. To avoid this warning for topics, and perhaps to be little more helpful, instead of linking to the keyword, this new code uses MkDocs tags listing to list pages with that keyword right on the topic page. Unless MkDocs changes when or how the check is done, we will get a warning for manually included links to keywords (tags), e.g., from the See also section.
This disables custom keywords build and disables the addons keyword integration in the CI workflow. The Python code to generate the keywords in Markdown is still in place, but it can be removed in the future possibly together with the custom HTML code (they are mixed together).
keywords.html: old doc - custom keyword index - MkDocs tag listing
(The difference in listed tools in the example is given by doc build with and without addons. The tag listing includes addons automatically since MkDocs processes all Markdown files at once in a separate build step.)
Topic page
(We may remove or completely redo the topics in the future, but this keeps external links working if any and the resulting pages look okay.)