docs: Add support for addon keywords to Markdown #5175
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 presuably 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.)
…. Add comment for no keywords section which we don't handle as an error. Use reg exp for matching the line and extracting the value.
wenzeslaus
added a commit
to wenzeslaus/grass
that referenced
this pull request
Feb 21, 2025
The original Markdown support from OSGeo#3849 breaks generating addon keywords on the doc build server because the parameter for addons used in the build script was ignored. The addon keywords are currently integated for 8.4, but are not integrated into the index for 8.5. This update should fix that. The new code allows for the original usage of the script where documentation directories are supplied as parameters. This assumes HTML documentation and corresponds to the usage on the build server. The intended usage from OSGeo#3849 for the new build where both Markdown and HTML are build using the script without the build system providing parameters is preserved. Finally, with parameters md <core-path> <addon-path>, the script allows for creating Markdown keyword list with optionally integrated addons using the paths provided. Unfortunately, ARCH_DISTDIR still needs to be set even in this case because it used directly a import time and a lot of other code uses that variable. This also adds a main function to separate the variables and handle the parameters in one place. Additionally, it creates the dict for the first letter TOC only for HTML where it is used (which allows the script to execute without the fixes for empty keyword list from OSGeo#5175).
This was referenced Feb 21, 2025
Member
Author
|
The fixes of links are now visible in the CI (after #5152). In CI Documentation, the number of lines in mkdocs output is reduced by roughly 800. The following warnings are present on main, but are not here as keyword links in addon files now correctly point to |
petrasovaa
approved these changes
Feb 25, 2025
wenzeslaus
added a commit
that referenced
this pull request
Feb 25, 2025
The original Markdown support from #3849 breaks generating addon keywords on the doc build server because the parameter for addons used in the build script was ignored. The addon keywords are currently integrated for 8.4, but are not integrated into the index for 8.5. This update should fix that. The new code allows for the original usage of the script where documentation directories are supplied as parameters. This assumes HTML documentation and corresponds to the usage on the build server. The intended usage from #3849 for the new build where both Markdown and HTML are build using the script without the build system providing parameters is preserved. Finally, with parameters md <core-path> <addon-path>, the script allows for creating Markdown keyword list with optionally integrated addons using the paths provided. Unfortunately, ARCH_DISTDIR still needs to be set even in this case because it used directly a import time and a lot of other code uses that variable. This also adds a main function to separate the variables and handle the parameters in one place. Additionally, it creates the dict for the first letter TOC only for HTML where it is used (which allows the script to execute without the fixes for empty keyword list from #5175). Updates the CI to use the renewed API to get addon keywords into keyword index in Markdown for both core and addons. Additionally, in the CI, it uses actual arch (just because it is possible), fixes logs dir path, uses more strict and verbose build.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The modifies the build scripts to support combining addon documentation into the main documentation. Links to keyword index, topics, and tool family now work from addons. Keyword index contains keywords from addons and link to addons.
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.)