parser: add markdown support

[landam]

This PR:

• adds a new option --md-description to produce module usage in Markdown
• updates RestructuredText to be synced with HTML interface description
• uses common codebase for Markdown and RestructuredText

Example:

v.buffer --md-description

Comparision of HTML (right) and Markdown (left):

Tasks

• solve all errors reported by markdownlint

[neteler]

A small example here would be nice:

grass/general/g.parser/g.parser.html

Line 297 in 4744671

<h2>reStructuredText</h2>

Like this:

<h2>Markdown</h2>

The flag <b>--md-description</b> added to a GRASS command
generates module interface description in Markdown, a lightweight
markup language. Example:

<div class="code"><pre>
v.in.db --md-description
</pre></div>

[landam]

Python script to validate generated Markdown files:

import subprocess
import grass.script as gs

# https://github.com/markdownlint/markdownlint
# sudo apt install ruby-mdl

for cmd in gs.get_commands()[0]:
    out_fn = "/tmp/" + cmd + ".md"
    fd = open(out_fn, "w")
    print([cmd, "--md-description"])
    p = subprocess.Popen([cmd, "--md-description"], stdout=fd)
    p.wait()
    fd.close()
    p = subprocess.Popen(["mdl", out_fn])
    p.wait()

[wenzeslaus]

Please, add the validation script to utils and run that in CI for couple tool in the additional checks workflow. This will ensure that both this PR is okay and any subsequent tweaks don't break it.

[neteler]

There is currently a compile error:

parser_rest_md.c: In function ‘usage_rest_md’:
parser_rest_md.c:267:29: error: format not a string literal and no format arguments [-Werror=format-security]
  267 |             fprintf(stdout, image_spec_rest);
      |                             ^~~~~~~~~~~~~~~
cc1: all warnings being treated as errors

[landam]

Please, add the validation script to utils and run that in CI for couple tool in the additional checks workflow. This will ensure that both this PR is okay and any subsequent tweaks don't break it.

In this stage I would say that there is no need for to run validation script in CI. CI validation will be probably performed when we will modify system for generating manuals to use markdown. This PR is just about adding --md-description option to the parser.

[landam]

The PR is ready for review. It adds a new option to the parser: --md-description. Usage:

v.to.db --md-description

In utils there is a script which checks whether generated markdown is valid. Usage:

Check single module:

python3 utils/md_isvalid.py -m v.to.db

Check all modules:

python3 utils/md_isvalid.py
...
--------------------------------------------------------------------------------
d.background
...
ximgview
--------------------------------------------------------------------------------
Modules processed 538 (0 failed)
--------------------------------------------------------------------------------

Currently all modules pass this test. This script can be integrated later into CI when the system for generating manual pages will be changed to use markdown (for this task a separated PR will be created).

Some validation rules are disabled (see utils/mdl_style.rb. Namely:

• MD013 (Line length) - some lines produced by GRASS parser can be longer that 80 characters (eg. module/option/flag description/label)
• MD034 (Bare URL used) - some lines produced by GRASS parser may contain URL, eg. g.extenstion
• MD037 (Spaces inside emphasis markers) - some lines produced by GRASS parser may contain multiple * characters, eg. v.to.db: s = perimeter / (2 \* sqrt(PI \* area)). It doesn't help to escape *, the rule disabled

Parser was also improved for two GRASS modules:

• r.mapcalc: use descriptions
• v.to.db: remove extra spaces in descriptions

[neteler]

Great work, tested with EN,DE, JA locales. Thanks!