[GRASS-git] [OSGeo/grass] e60ee6: docs: Add support for addon keywords to Markdown (...

[Vaclav Petras]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: e60ee63e15fcd27cf2d79fadc028fa6106eba040
      https://github.com/OSGeo/grass/commit/e60ee63e15fcd27cf2d79fadc028fa6106eba040
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2025-02-25 (Tue, 25 Feb 2025)

  Changed paths:
    M man/build_keywords.py
    M utils/mkmarkdown.py

  Log Message:
  -----------
  docs: Add support for addon keywords to Markdown (#5175)

The modifies the build scripts to support combining addon documentation into the main documentation.

HTML_PAGE_FOOTER_PAGES_PATH build-only helper env var is used to provide a prefix for URL during the build of addons (this would be set to '../'). The already generated keyword section is replaced by a new one which has the links with a prefix. This copies how the HTML documentation deals with the keywords. The name HTML_PAGE_FOOTER_PAGES_PATH comes from the usage in the HTML documentation and does not apply for Markdown as the footer is not generated on the page level. Following the HTML documentation, the links are corrected during processing in Python rather than during the original creation in the command line parser C code.

Separate, yet related, issue is dealing with empty keywords in the tools. The original code just fails with addons which don't have any keywords. This addresses that issue by printing the message to stderr, but skipping the empty keyword. (The HTML does not have that issue presumably because the parsed list of keywords is empty while the Markdown parsing results in an one empty item in a list. This may change how this is handled in Markdown in the future depending on how we deal with custom keywords versus mkdoc tags.)

Handle separately different missing keyword cases: No keywords, but the keywords key is present in metadata, and empty keyword in a list. Add comment for no keywords section which we don't handle as an error. Use regular expression for matching the line and extracting the value rather than multistep identification and splitting with basic string manipulation.

In CI, this reduces number of broken links identified by mkdocs from addons to the main doc because the existing keywords are now linked (including tool family and existing topics).



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