canonical / canonical/sphinx-stack
Add logging levels to make the update script easier to troubleshoot
- Dominant language
- No language data
- Stars
- 37
- Forks
- 77
- Avg merge
- 1d 5h
- Merged PRs (30d)
- 3
Description
While working on PR #424, I realized that troubleshooting the [update](https://github.com/canonical/sphinx-docs-starter-pack/blob/main/docs/.sphinx/update_sp.py) script isn't intuitive because the logging levels aren't properly used. I found it challenging to distinguish between the script's actions and the outputs it generates.
I had this issue when outputting the item variable at [Line 141](https://github.com/canonical/sphinx-docs-starter-pack/blob/dd7be04b644b28afcdee118e25c7f001e06fa817/docs/.sphinx/update_sp.py#L141).
In an old https://github.com/canonical/sphinx-docs-starter-pack/pull/357#discussion_r2011275564, one of the maintainers said, Using a print "... is intended to provide specific information on what the script is doing. Logging is to debug issues." However, this statement isn't entirely accurate. Logging works [beyond debugging issues](https://docs.python.org/3/library/logging.html#logging-levels).
There are parts where a banner-like warning is outputted, for example, at [Lines 153-157](https://github.com/canonical/sphinx-docs-starter-pack/blob/dd7be04b644b28afcdee118e25c7f001e06fa817/docs/.sphinx/update_sp.py#L153). It would have made more sense to use a one-line warning log level there and not just several print outputs. So, while troubleshooting, you know that this is a log-related warning and not just a banner. Sometimes, if you aren't careful, you might have assumed the banner was outputted from what you are troubleshooting.
Contributor guide
Assessment
This issue has not been assessed yet.