[GRASS-git] [OSGeo/grass] 8efcc3: grass.tools: Add Tools API to generated tools doc ...

[Vaclav Petras]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: 8efcc3670171b2114be8c3684e99b78bae0954e2
      https://github.com/OSGeo/grass/commit/8efcc3670171b2114be8c3684e99b78bae0954e2
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2025-07-28 (Mon, 28 Jul 2025)

  Changed paths:
    M lib/gis/parser_local_proto.h
    M lib/gis/parser_md.c
    M lib/gis/parser_md_python.c

  Log Message:
  -----------
  grass.tools: Add Tools API to generated tools doc (#6015)

This adds grass.tools.Tools from #2923 to the generated documentation of individual tools as a new tab similar to the grass.script tab. The documentation and treatment of parameters is the same at this points in grass.tools as in grass.script except for _io.StringIO_.

The _io.StringIO_ type is added based on the gisprompt on a best-guess basis. The current parser metadata don't contain explicit machine-readable information about stdin being allowed. Parser then does not know whether or not a specific tool supports stdin for one of its parameters. The stdin is resolved while opening the file by a library function call at the level of individual tools, but during command line parsing, the parser merely allows for dash being provided instead of a filename. The resulting documentation now contains `"'-' for standard input"` or the like based on what is in each tool. This is slightly misleading for the Tools API because `"-"` won't do anything useful because the only way to supply stdin at this point is _io.StringIO_. However, without extending the parser metadata, I don't see any way how to make it better.

The first first parameter spacing and comma in short doc now needs a special handling because before, we always had a first parameter, namely the name of the tool.  

A care was given to the wording of the experimental part to be clear what part of our API is the experimental one.

This also fixes and clarifies the comment about parse_command versus read_command and run_command.



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