-
-
Notifications
You must be signed in to change notification settings - Fork 307
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
grass.script: Explain setting of debug level #2313
Conversation
Explain that DEBUG level is set with `g.gisenv`.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
Maybe an example in g.gisenv man page? But this seems to be yet another candidate for a tutorial/topic/overview/intro page. |
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
|
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. |
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. |
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? |
@wenzeslaus ok for merge? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice and clear!
* libpython core docs: explain setting of debug level
* libpython core docs: explain setting of debug level
* libpython core docs: explain setting of debug level
* libpython core docs: explain setting of debug level
Add to
script.core.debug()
(manual) which debug levels are recommended (seeg.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: