docs: Generate manual from markdown using mkdocs

[landam]

Goal

Build user manual from Markdown using mkdocs

How to test

1. Install requirements, see man/mkdocs/requirements.txt
2. Create file /tmp/code.lua:

function CodeBlock (cb)
    return pandoc.RawBlock('markdown', '```\n' .. cb.text .. '\n```\n')
end

3. Convert HTML files to Markdown:

for f in `find . -name *.html`; do echo $f; cat $f | sed 's#<div class="code"><pre>#<pre><code>#g' | sed 's#</pre></div>#</code></pre>#g' | pandoc --from=html --to=markdown --lua-filter /tmp/code.lua > ${f%%.html}.md;done

4. Compile GRASS
5. Open dist.x86_64-pc-linux-gnu/docs/mkdocs/site/index.html in web browser

Tasks

Critical:

• fix CI
• man : integrate changes from main
• separate makefile rules (Markdown.make, MarkdownRules.make) ?
• make install
• fix gui/script/ compilation
• fix compilation issue in raster
• fix compilation issue in man
• fix segfault in --md-description
• fix code blocks
• fix commit link

Important:

• implement build_md.py and indices
• solve warnings generated by mkdocs
• add missing meta page comments to MD files (as YAML metadata block)
• consider to keep supporting HTML in g.extension for the addons
• parser_standard_options: choose formatting than table
• index: choose better formatting than table
• replace html with md in links
• remove toc-related code from mkmarkdown.py and change mkdocs style to show page-related TOC
• fix "## DESCRIPTION" appearance from keyword list
• logo points to index.html
• site_name to "GRASS GIS 8.5.0dev Reference Manual"
• fix menu items
• implement parser_standard_options
• implement manual_gallery
• use theme footer

Nice to have:

• implement class_graphical (https://grass.osgeo.org/grass84/manuals/class_graphical.html is empty ???)
• manual_gallery: different number of images (md vs html), fix layout (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

Tasks before merge

• rebase main and regenerate MD files from HTML once again

Tasks after merge(?)

• remove rest-related scripts
• generate man from markdown
• remove HTML-based documentation and clean-up scripts

[neteler]

Hi @landam! After discussion with @wenzeslaus, we would like to propose to remove the auto-converted MD manual pages from this PR to reduce its size.

Once the software part of this PR is working

• we can create a new PR to add the auto-converted MD manual pages
• then compare them to the original HTML pages and update/fix these MD files if necessary
• and finally remove the HTML pages in another PR.

This way it is easier to handle/review and less work in this PR. What do you think?

[landam]

Hi @landam! After discussion with @wenzeslaus, we would like to propose to remove the auto-converted MD manual pages from this PR to reduce its size.
This way it is easier to handle/review and less work in this PR. What do you think?

@neteler Make sense to me, done in 682d266

[github-actions]

[ruff] _{reported by reviewdog 🐶}

Suggested change

	import operator

[github-actions]

[ruff] _{reported by reviewdog 🐶}

Suggested change

	classes.sort(key=lambda tup: tup[0])
	classes.sort(key=operator.itemgetter(0))

[github-actions]

[ruff] _{reported by reviewdog 🐶}

Suggested change

	build_full_index("md")
	build_full_index("md")

[github-actions]

[ruff] _{reported by reviewdog 🐶}

Suggested change

	if test_length % 4 == 0 and not test_length == all_keys:
	if test_length % 4 == 0 and test_length != all_keys:

[github-actions]

[ruff] _{reported by reviewdog 🐶}

Suggested change

	if not response.code == 200:
	if response.code != 200: