Add logging levels to update script

[mariaclara-sia]

• Have you updated CHANGELOG.md with relevant non-documentation file changes?
• Have you updated the documentation for this change?

---

The update script presents users with information of varying importance using print statements. Issue #428 states how difficult this can make the output to parse. This PR replaces those print statements with logging calls. Manual tests are described below.

Manual tests

New logging.warning() and logging.info() calls were introduced to replace print statements in the update script of the starter-pack. The command-line tests below demonstrate how these calls are reached. Each test is independent of other tests.

Prerequisite for tests

Clone this branch of the starter-pack.

$ git clone -b DOCPR-2396-logging-update-script git@github.com:canonical/sphinx-docs-starter-pack.git

Change to the starter-pack's docs directory and run make html, then activate the resulting Python virtual environment.

$ cd sphinx-docs-starter-pack/docs
$ make html                            # trigger the docs build
$ source .venv/bin/activate            # activate the virtual environment

From inside the virtual environment, change to the .sphinx subdirectory and run the update script. The script should run with no issues.

(.venv)~$ cd .sphinx
(.venv)~$ ./update_sp.py

Test 1: Missing version file (Lines 47-48)

Temporarily rename the the version file so that the update script fails to find it in the expected place. (Triggers: lines 47-48)

(.venv)~$ mv version version_2

Run the update script. Warnings are shown.

(.venv)~$ ./update_sp.py

WARNING:root:You need to update to at least version 1.0.0 of the starter 
pack to start using the update function.                                # Line 47
WARNING:root:You may experience issues using this functionality.        # Line 48
Traceback (most recent call last):                                      # error message
  ...                                                                   # error message

To clean up, restore the original version file.

(.venv)~$ mv version_2 version

Test 2: Outdated starter-pack version, missing files (Lines 101 / 64, 149, 80-81, 86-88, 94-96)

Set the LOG_INFO environment variable to True, which sets the update script's logging level to INFO. Since INFO is a higher level than DEBUG, the pre-existing logging.debug() calls will be skipped, resulting in cleaner log output.

(.venv)~$ export LOGGING_INFO=True

Run the update script normally. Log info is shown (line 101).

(.venv)~$ ./update_sp.py

INFO:root:This version is up to date.                                   # Line 101

Temporarily replace the existing version file with one that declares the version to be "0.1" The update script assumes the starter-pack is outdated. (Triggers: lines 64, 149, 80-81, 86-88)

(.venv)~$ mv version version_2                    # rename the version file
(.venv)~$ echo 0.1 > version                      # create a 0.1 version file

Temporarily rename the pa11y.json file (one of a few monitored files) so that the update script fails to find it in the expected place. (Triggers: lines 94-96 + creation of some new files)

(.venv)~$ mv pa11y.json pa11y.json_2              # rename the pa11y.json file

Run the update script. Warnings and log info are shown.

(.venv)~$ ./update_sp.py 

WARNING:root:Starter pack is out of date.                               # Line 64
WARNING:root:THIS UPDATE SCRIPT IS OUT OF DATE. YOU MAY NEED TO RUN 
ANOTHER UPDATE AFTER UPDATING TO THE FILE IN '.sphinx/updates'.         # Line 149
INFO:root:SEE CURRENT CHANGELOG:                                        # Line 80
INFO:root: sphinx-docs-starter-pack changelog                           # Line 81
  ...                                                                   # changelog body text

INFO:root:Differences have been identified in static files.             # Line 86
INFO:root:Updated files have been downloaded to '.sphinx/update'.       # Line 87
INFO:root:Validate and move these files into your '.sphinx/' directory. # Line 88
INFO:root:NOTE: New files have been downloaded                          # Line 94
INFO:root:See 'NEWFILES.txt' for all downloaded files                   # Line 95
INFO:root:Validate and merge these files into your '.sphinx/' directory # Line 96

To clean up, remove newly created files and restore the original pa11y.json file. Delete the 0.1 version file and restore the original version file. Finally, unset the LOG_INFO environment variable.

(.venv)~$ rm update/pa11y.json                    # remove downloaded pa11y.json
(.venv)~$ rm NEWFILES.txt                         # remove generated NEWFILES.txt
(.venv)~$ mv pa11y.json_2 pa11y.json              # restore the original pa11y.json file
(.venv)~$ rm version                              # delete the 0.1 version file
(.venv)~$ mv version_2 version                    # restore the original version file
(.venv)~$ unset LOGGING_INFO

Test 3: Missing requirements.txt file (Lines 127-29)

Temporarily rename the ../requirements.txt file so that the update script fails to find it in the expected place. (Triggers: lines 127-129)

(.venv)~$ mv ../requirements.txt ../requirements.txt_2

Run the update script. Warnings are shown.

(.venv)~$ ./update_sp.py 

WARNING:root:requirements.txt not found                                 # Line 127
WARNING:root:The updated starter pack has moved requirements.txt out of 
the '.sphinx' dir                                                       # Line 128
WARNING:root:requirements.txt not checked, please update your 
requirements manually                                                   # Line 129

To clean up, restore the original ../requirements.txt file.

(.venv)~$ mv ../requirements.txt_2 ../requirements.txt

Test 4: Missing dependencies in requirements.txt (Line 123)

Temporarily comment out the last line of ../requirements.txt (prepend a hash "# "). This omits one dependency (in this case, vale) from the set of dependencies that the update script extracts from the .txt file. (Triggers: line 123)

(.venv)~$ sed -i '$ s/^/# /' ../requirements.txt

Run the update script. Warnings are shown.

(.venv)~$ ./update_sp.py
WARNING:root:You may need to add the following packages to your 
requirements.txt file: {'vale'}                                         # Line 123

To clean up, uncomment the last line of ../requirements.txt (remove the prepended hash "# ").

(.venv)~$ sed -i '$ s/^# //' ../requirements.txt

Clean up after tests

Exit the virtual environment.

(.venv)~$ deactivate
$