docs: Replace grass-stable URLs by relative URLs #5527
Conversation
The core and addons doc mostly use absolute paths to refer to each other. However, when the docs are build together, the links may point to a wrong version. This is now even a bigger issue with Sphinx-based Python doc which is more linked from the main doc than it was before. Having the absolute URLs pointing to grass-stable is still a good solution. It is straigforward. It works locally and when each piece is build separately. The new script and the build step in CI is done after the two documentations are put together and with anticipation that libpython will be build into it. The replacement is done on Markdown level, so MkDocs will complain that the libpython links are broken, but that does not break the build and hopefully having both MkDocs and Sphinx docs is something to change in the future. No replacements are done for links from libpython, but there are currently none. The only links which are there are relative already.
The core and addons doc mostly use absolute paths to refer to each other. However, when the docs are build together, the links may point to a wrong version. This is now even a bigger issue with Sphinx-based Python doc which is more linked from the main doc than it was before. Having the absolute URLs pointing to grass-stable is still a good solution. It is straigforward. It works locally and when each piece is build separately. The new script and the build step in CI is done after the two documentations are put together and with anticipation that libpython will be build into it. The replacement is done on Markdown level, so MkDocs will complain that the libpython links are broken, but that does not break the build and hopefully having both MkDocs and Sphinx docs is something to change in the future. No replacements are done for links from libpython, but there are currently none. The only links which are there are relative already.
|
We need to check here if it actually works in the CI by inspecting the artifact once it's build. |
github-project-automation
bot
moved this to In Progress
in GRASS Markdown Documentation
github-actions
bot
added
CI
wenzeslaus
changed the title
|
Examining the artifact, this works well for links from core to libpython (e.g., from Python intro) and to addons (e.g., from r.mapcalc to r.bitpattern). It does not work from addons to core (e.g., v.surf.icw). Also, the test Even more stuff: Additionally, we have a lot of versioned URLs to addons in the source code, so these should be eventually replaced by version-less URLs: - https://grass.osgeo.org/grass8/manuals/addons/r.stream.order.html
+ https://grass.osgeo.org/grass-stable/manuals/addons/r.stream.order.htmlDoing the replacement before MkDocs runs means that a lot warnings are produced by MkDocs. I know that ahead of time, but perhaps it is worth revisiting. Some are hard to fix because libpython is simply added only after MkDocs step (or maybe we can add that ahead of time and thus have the links checked by MkDocs?): Some are fixable if we not only replace the base URL but also the extension: Perhaps even adding index.md for the directories? |
|
Usually, for doc builders like this, you have to make the links work with the files you have in the repo (with the advantage that when previewing in GitHub or your IDE, links work correctly), and the doc builder makes sure to have the links work with what it generates. Then, there's often the option to do url mappings for having some internal/external URLs point to something else or to external/internal URLs. For addons->grass or grass->addons, since it is a different repo, I'm not sure what is best to do. Have full URLs in the source files, but then adjust the docs url mappings to recognize that these URLs can be converted to relative, as they are hosted from the same domain? |
The core and addons doc mostly use absolute paths to refer to each other. However, when the docs are build together, the links may point to a wrong version. This is now even a bigger issue with Sphinx-based Python doc which is more linked from the main doc than it was before.
Having the absolute URLs pointing to grass-stable is still a good solution. It is straightforward. It works locally and when each piece is build separately.
The new script and the build step in CI is done after the two documentations are put together and with anticipation that libpython will be build into it. The replacement is done on Markdown level, so MkDocs will complain that the libpython links are broken, but that does not break the build and hopefully having both MkDocs and Sphinx docs is something to change in the future. No replacements are done for links from libpython, but there are currently none. The only links which are there are relative already.