[GRASS-git] [OSGeo/grass] f48be6: docs: Add Python to the generated Markdown tool do...

[Vaclav Petras]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: f48be6788bbccc13526a35c699f90fdb745a624d
      https://github.com/OSGeo/grass/commit/f48be6788bbccc13526a35c699f90fdb745a624d
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2025-04-10 (Thu, 10 Apr 2025)

  Changed paths:
    M lib/gis/parser_dependencies.c
    M lib/gis/parser_local_proto.h
    M lib/gis/parser_md.c
    A lib/gis/parser_md_cli.c
    A lib/gis/parser_md_common.c
    A lib/gis/parser_md_python.c
    M man/mkdocs/mkdocs.yml

  Log Message:
  -----------
  docs: Add Python to the generated Markdown tool doc (#5490)

This completely revamps the generated header for tool documentation pages, and it adds Python syntax for the tool and Python-oriented parameter description. The Python part is similar, but not the same to what is generated by Sphinx autodoc. I tried to make like it while accomodating the metadata we have (key desc strings, label and description for flags), while working with the Markdown syntax (we generate pure and simple Markdown which is only later translated to HTML in generic way, not knowing about the context or language).

Most of the headings are removed for both CLI and Python, key-value parameters go before flags for both, and the idea makes heavy use of synchronized tabs.

Generate Python examples based on format=json|csv (or -g without file output aka new prompt) and show first parameter from a group of 'at least one required'. CLI examples are simpler, not dealing with the text outputs, but showing the same info.

Using general Command line and Python (grass.script). This makes sense for the interface part. The examples may use Bash specifically and that will complicate things in the future.

Split markdown code into four files: main, CLI, Python, common. Add function parameter file instead of hardcoding stdout. Fix CLI synopsis for tools without flags.

Use key_desc to determine if the type is tuple. Parser treats the parameter as tuple, so the basic type is actually wrong (e.g. string or iterable of ints rather than int). Even the synopsis for Python is wrong without this info as ints or floats can just be comma-separated without that info because default answer (values) will include multiple values for tuples. Now tuples in default values are represented as strings in synopsis (aka short version) which is the simpler solution, but I used the more complicated code only for the actual type in the parameters section (aka long version). The key_desc to tuple comes from parser.c code which is little different and requires a separate change.

Separate Python types by pipe and use the type hints we are using elsewhere. Make optional/required in italics to make it more distinct.

Introduce a 'Used as' line which shows what parser calls age (old/new) as input/output and desc/prompt from gisprompt followed by key_desc in italics. Neither of those is mandatory, but all can appear. The second item - element - in key_desc is not used in the doc, but that's what actually drives the usage internally in parser. This may create some discrepancies or may need to be resolved later (cell versus raster, for vectors both is vector, for signature files desc is very general, element is more specific but hard to read).

The short flags parameter and long flags try to mimic the other parameters. Just the letters for short flags are more like top-level parameters because they can have both label and description.



To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications