canonical / canonical/sphinx-stack

Add logging levels to make the update script easier to troubleshoot

Open
#428 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.