grass.script: Explain setting of debug level

[neteler]

Add to script.core.debug() (manual) which debug levels are recommended (see g.message, manual).
The debug message visibility is controlled by the DEBUG level set with g.gisenv (see manual).

Here some examples how the DEBUG message level management generally works:

## set DEBUG=1
GRASS nc_spm_08_grass7/user1: > g.gisenv set="DEBUG=1"
...

# msg visible:
GRASS nc_spm_08_grass7/user1: > g.message -d message="my debug message" debug=1
D1/1: G_set_program_name(): g.message
D1/1: my debug message"
D1/1: G_set_program_name(): g.gisenv
D1/1: G_set_program_name(): g.gisenv

# msg not visible
GRASS nc_spm_08_grass7/user1: > g.message -d message="my debug message" debug=2
D1/1: G_set_program_name(): g.message
D1/1: G_set_program_name(): g.gisenv
D1/1: G_set_program_name(): g.gisenv

## switch to DEBUG=2
GRASS nc_spm_08_grass7/user1: > g.gisenv set="DEBUG=2"
...

# msg now visible
GRASS nc_spm_08_grass7/user1: > g.message -d message="my debug message" debug=2
D1/2: G_set_program_name(): g.message
D2/2: G_file_name(): path = /home/mneteler/grassdata/nc_spm_08_grass7/user1
D2/2: my debug message
D1/2: G_set_program_name(): g.gisenv
D1/2: G_set_program_name(): g.gisenv

## back to debug silence
GRASS nc_spm_08_grass7/user1: > g.gisenv set="DEBUG=0"

[wenzeslaus]

The current text mixes setting debug level for the message and setting debug level to control which debug messages are displayed.

Perhaps split the text into a short (one line) description of the parameter and one or two sentences in a separate paragraph providing details about the debug level (such as g.gisenv).

[wenzeslaus]

I think the syntax does not work that way. This is what is rendered:

The code block is another paragraph, not part of the parameter description.

Keeping the parameter description to just one line is the safe way syntactically, but also in terms of complexity of the text. If it is so complex it needs more than few words, you better explain it in the text with proper sentences and paragraphs. After all, this is how Python documents most functions. (NumPy is different but that's also using different syntax in the docstrings which would be a good discussion for another time.)

The code block is assumed to be Python, so verbatim would need something else. This is more a table, but perhaps it should be a sentence or two. The assignment of recommended meaning to levels lacks context and it is misleading in terms of what is recommend, the numbers or their meanings? Recommend for who?

Perhaps something like "Use 1 for messages generated once of few times, 2 for messages generated for each raster row or vector line, ..."

How does 0 make sense as a parameter here anyway?

[wenzeslaus]

Here some examples how the DEBUG message level management generally works:

Maybe an example in g.gisenv man page? But this seems to be yet another candidate for a tutorial/topic/overview/intro page.

[BadAssassin]

Debug levels are explained in doc/debugging.txt.  I'm sure there is a better place for it and examples are always useful. It should definitely be referenced or explained in g.gisenv man page.

On 4/19/2022 7:28 AM, Vaclav Petras wrote: Here some examples how the DEBUG message level management generally works: Maybe an example in g.gisenv man page? But this seems to be yet another candidate for a tutorial/topic/overview/intro page. Message ID: ***@***.***>

-- Best Regards, -Brad

[BadAssassin]

Just reviewed the entire thread...

Keep in mind that the debugging routines were designed to debug the core C code. 0 is there to disable debugging (this code generally gets removed for release builds). It is okay to add debug levels for python (ie. 2) without affecting how debugging works. Just document the ones that are python specific and avoid changing the levels that already exist.

[wenzeslaus]

Hm, doc/debugging.txt, never seen that. It is little too C-only, but otherwise I guess that's exactly the page I had in mind. I guess first step would be to turn this to Markdown. The second is adding some of these Markdown files to HTML doc.

[wenzeslaus]

...the debugging routines were designed to debug the core C code. ...add debug levels for python...

See the implementation, currently, the Python function debug which is in question just calls g.message if debug level is greater than zero. (The sync to gisenv is done in debug_level.) Python code does not add any levels. Is that what you are thinking?

[neteler]

I think the syntax does not work that way

Ok, fixed, now it looks like this:

[neteler]

@wenzeslaus ok for merge?

[wenzeslaus]

Nice and clear!