docs: General todos for Markdown

[wenzeslaus]

This is a general todo list for the new documentation which originally lived in #3849 (I transferred the unresolved todos only). Feel free to add more basic issues here, but use smaller issues and the project for specific tasks if possible rather than turning this into a un-closeable mega issue.

Needed

• [x] add missing meta page comments to Markdown files (as YAML metadata block) #5169
• [x] keep supporting HTML-only in g.extension for the addons
• [x] parser_standard_options: use formatting other than a table #5235
• [x] main index: choose better formatting than the current table #5207
• [x] add GRASS_PROXY to Markdown build (not ported from HTML to Markdown in #3849; variable introduced in #2100) #5236
• [ ] generate man from Markdown (and not from HTML) #5358

Notes on man:

-$(MANDIR)/%.$(MANSECT): $(HTMLDIR)/%.html
+$(MANDIR)/%.$(MANSECT): $(MDDIR)/source/%.md

Nice to have

• [x] manual_gallery: different number of images in Markdown vs HTML (run in man dir: GISBASE="/home/martin/src/grass/dist.x86_64-pc-linux-gnu" ARCH="x86_64-pc-linux-gnu" ARCH_DISTDIR="/home/martin/src/grass/dist.x86_64-pc-linux-gnu" VERSION_NUMBER=8.5.0dev VERSION_DATE=2024 python3 ./build_manual_gallery.py) and see dist.x86_64-pc-linux-gnu/docs/markdown/site/manual_gallery.html and https://grass.osgeo.org/grass84/manuals/manual_gallery.html #5247
• [x] manual_gallery: fix layout (now large images without descriptions comparing to thumbnails with descriptions) #5250

Future

• [x] revise usage of keywords and tags from user perspective (what should a reader see) #5446 and #5444
• [x] revise usage of keywords and tags from implementation perspective (valid YAML syntax and duplication) #5320
• [ ] remove Markdown code for generating keyword index page (possibly just remove it together with HTML)
• [ ] revise or clean up the graphical index (index pages) - drop it or make it the only index pages
• [ ] remove reStructuredText-related code and scripts (aka rest or rst), maybe not all of it because some of it is used (and useful) for auto-generated docstring in Python.
• [ ] remove HTML documentation files
• [ ] remove custom HTML documentation from build system and build scripts

[cwhite911]

main index: choose better formatting than the current table

I have an idea for this one, but it will be easier just to show in a draft PR.

[echoix]

I might have something to add to the todo: there's current grass-devel version of the mkdocs site, in the development tab, multiple links go to the wrong "version" of the content:

• Python library goes to the old grass-stable (grass 8.4)
• Testing goes to the old grass-stable (grass 8.4)
• Addons goes to the grass-stable (grass 8.4)

Also to take note when doing the releases: make sure our repo URLs that point to the main branch (for the grass-devel version) end up mapping the correct branch. That means that when building for a release of 8.5, the URLs should map to releasebranch_8_5, or even the tag used to generate that page. For example, on the same development tab, the "CONTRIBUTING file on GitHub" should be the one that belongs to the branch that the mkdocs was run for (so we could rebuild the site for a specific previous version).

[neteler]

I might have something to add to the todo: there's current grass-devel version of the mkdocs site, in the development tab, multiple links go to the wrong "version" of the content:

* Python library goes to the old grass-stable (grass 8.4)
* Testing goes to the old grass-stable (grass 8.4)
* Addons goes to the grass-stable (grass 8.4)

Yes, and a few more files might need related updates of changing grass-stable -> grass-devel:

ag --markdown "grass.osgeo.org/grass-stable" -l
raster/r.buildvrt/r.buildvrt.md
raster/r.covar/r.covar.md
raster/r.mapcalc/r.mapcalc.md
raster/r.texture/r.texture.md
raster/r.smooth.edgepreserve/r.smooth.edgepreserve.md
scripts/g.download.project/g.download.project.md
vector/v.info/v.info.md
doc/jupyter_intro.md
doc/interfaces_overview.md
doc/python_intro.md
imagery/i.gensigset/i.gensigset.md
imagery/i.landsat.toar/i.landsat.toar.md
imagery/i.pca/i.pca.md

[neteler]

Yes, and a few more files might need related updates of changing grass-stable -> grass-devel:

Addressed in #5809