[GRASS-git] [OSGeo/grass] 17f611: docs: Replace keywords index by MkDocs tags (#5446)

[Vaclav Petras]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: 17f611d9d0c8146ffa4200a6ede0129005bd6f74
      https://github.com/OSGeo/grass/commit/17f611d9d0c8146ffa4200a6ede0129005bd6f74
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2025-03-26 (Wed, 26 Mar 2025)

  Changed paths:
    M .github/workflows/documentation.yml
    M man/Makefile
    M man/build_keywords.py
    M man/build_topics.py
    A man/mkdocs/keywords.md
    M man/mkdocs/mkdocs.yml
    A man/mkdocs/overrides/fragments/tags/default/listing.html
    R man/mkdocs/tags.md

  Log Message:
  -----------
  docs: Replace keywords index by MkDocs tags (#5446)

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

To show more context, modify the tag listing template to show description for each tool (page). This shows description for each tool and makes 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.)



To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications