make SP files linter compliant

.github/workflows/automatic-doc-checks.yml

@@ -2,7 +2,7 @@ name: Main Documentation Checks
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
   # Manual trigger
   workflow_dispatch:
@@ -15,4 +15,4 @@ jobs:
   documentation-checks:
     uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
     with:
-      working-directory: 'sp-docs'
+      working-directory: "sp-docs"

init.sh

@@ -16,21 +16,20 @@ if [ -z "$install_directory" ]; then
 fi
 
 # Check if md or rst is preferred for the documentation being built
-promptForFileChoice()
-{
-while true; do
-    read -p "Will you be using the 'rst' or 'md' file format for the documentation (default: 'rst'): " filetype_choice
+promptForFileChoice() {
+    while true; do
+        read -p "Will you be using the 'rst' or 'md' file format for the documentation (default: 'rst'): " filetype_choice
 
-    filetype_choice=${filetype_choice:-rst}
+        filetype_choice=${filetype_choice:-rst}
 
-    if [ "$filetype_choice" = "md" ] || [ "$filetype_choice" = "rst" ]; then
-        file_type="$filetype_choice"
-        echo "Setting filetype to: $file_type"
-        break
-    else
-        echo "Invalid input. Please enter either 'md' or 'rst':"
-    fi
-done
+        if [ "$filetype_choice" = "md" ] || [ "$filetype_choice" = "rst" ]; then
+            file_type="$filetype_choice"
+            echo "Setting filetype to: $file_type"
+            break
+        else
+            echo "Invalid input. Please enter either 'md' or 'rst':"
+        fi
+    done
 }
 
 # If default variable for filetype choice is defined in CI then don't prompt user for choice
@@ -82,7 +81,7 @@ if [ -f "$install_directory/.gitignore" ]; then
     read -p "Do you want to append the list of ignored files for Sphinx docs to the existing .gitignore? Enter 'n' to skip. (y/n): " confirm
     if [ "$confirm" = "y" ]; then
         echo "Appending contents to the existing .gitignore..."
-        cat "$temp_directory/sp-files/.gitignore" >> "$install_directory/.gitignore"
+        cat "$temp_directory/sp-files/.gitignore" >>"$install_directory/.gitignore"
     else
         echo "Operation skipped by the user. Add the .gitignore rules for the Sphinx docs to your .gitignore file manually."
     fi
@@ -100,9 +99,9 @@ if [ -f "$install_directory/Makefile" ]; then
         echo "Creating a backup: $backup_makefile"
         cp "$existing_makefile" "$backup_makefile"
 
-        echo "Appending Sphinx docs targets to the existing Makefile..." 
-        echo "" >> "$existing_makefile"    # Add a new line before appending the contents
-        cat "$temp_directory/sp-files/Makefile" >> "$existing_makefile"
+        echo "Appending Sphinx docs targets to the existing Makefile..."
+        echo "" >>"$existing_makefile" # Add a new line before appending the contents
+        cat "$temp_directory/sp-files/Makefile" >>"$existing_makefile"
     else
         echo "Operation skipped by the user. Add the Makefile targets for Sphinx docs manually."
     fi
@@ -153,7 +152,7 @@ if [ "$install_directory" != "." ]; then
             read -p "Do you want to append the contents of $install_directory/.wokeignore to the existing .wokeignore? Enter 'n' to skip. (y/n): " confirm
             if [ "$confirm" = "y" ]; then
                 echo "Appending contents to the existing .wokeignore..."
-                cat "$install_directory/.wokeignore" >> .wokeignore
+                cat "$install_directory/.wokeignore" >>.wokeignore
                 rm "$install_directory/.wokeignore"
             else
                 echo "Operation skipped by the user. Add the rules from $install_directory/.wokeignore to your .wokeignore file manually."

sp-files/.github/workflows/automatic-doc-checks.yml

@@ -2,7 +2,7 @@ name: Main Documentation Checks
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
   # Manual trigger
   workflow_dispatch:
@@ -15,4 +15,4 @@ jobs:
   documentation-checks:
     uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
     with:
-      working-directory: '.'
+      working-directory: "."

sp-files/.github/workflows/periodic-style-checks.yml

@@ -9,12 +9,11 @@ jobs:
     name: Style checker
     runs-on: ubuntu-22.04
     defaults:
-        run:
-            shell: bash
-            working-directory: 'sp-docs'
+      run:
+        shell: bash
+        working-directory: "sp-docs"
     steps:
       - uses: actions/checkout@v4
       - name: Run vale
         run: |
           make vale
-

sp-files/.github/workflows/sphinx-python-dependency-build-checks.yml

@@ -15,10 +15,9 @@ on:
   - pull_request
   - workflow_dispatch
 
-
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true  
+  cancel-in-progress: true
 
 jobs:
   build:
@@ -45,4 +44,4 @@ jobs:
           make -f Makefile.sp \
             sp-install \
             PIPOPTS="--no-binary :all:" \
-            || ( cat .sphinx/venv/pip_install.log && exit 1 )
+            || ( cat .sphinx/venv/pip_install.log && exit 1 )

sp-files/.readthedocs.yaml

@@ -22,9 +22,9 @@ sphinx:
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
 formats:
-   - pdf
+  - pdf
 
 # Optionally declare the Python requirements required to build your docs
 python:
-   install:
-   - requirements: sp-docs/.sphinx/requirements.txt
+  install:
+    - requirements: sp-docs/.sphinx/requirements.txt

sp-files/.sphinx/_static/css/pdf.css

@@ -1,6 +1,6 @@
 /* Only relevant for specific PDF generation issues */
 
-.rubric > .hclass2 {
+.rubric>.hclass2 {
     display: block;
     font-size: 2em;
     border-radius: .5rem;

sp-files/.sphinx/_templates/header.html

@@ -49,4 +49,4 @@
 
     </ul>
   </div>
-</header>
+</header>

sp-files/.sphinx/get_vale_conf.py

@@ -3,10 +3,10 @@
 import requests
 import os
 
-DIR=os.getcwd()
+DIR = os.getcwd()
 
-def main():
 
+def main():
     if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"):
         print("Vale directory exists")
     else:
@@ -24,18 +24,21 @@ def main():
         print("Vocab directory exists")
     else:
         os.makedirs(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical")
-    
+
     url = "https://api.github.com/repos/canonical/praecepta/contents/styles/config/vocabularies/Canonical"
     r = requests.get(url)
     for item in r.json():
         download = requests.get(item["download_url"])
         file = open(".sphinx/styles/config/vocabularies/Canonical/" + item["name"], "w")
         file.write(download.text)
         file.close()
-    config = requests.get("https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini")
+    config = requests.get(
+        "https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini"
+    )
     file = open(".sphinx/vale.ini", "w")
     file.write(config.text)
     file.close()
 
+
 if __name__ == "__main__":
     main()

sp-files/.sphinx/metrics/build_metrics.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# shellcheck disable=all
 
 links=0
 images=0
@@ -11,4 +12,4 @@ images=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {}
 # summarise latest metrics
 echo "Summarising metrics for build files (.html)..."
 echo -e "\tlinks: $links"
-echo -e "\timages: $images"
+echo -e "\timages: $images"

sp-files/.sphinx/metrics/source_metrics.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+# shellcheck disable=all
 
 VENV=".sphinx/venv/bin/activate"
 
@@ -26,9 +27,9 @@ else
 
     for file in *.md *.rst; do
         if [ -f "$file" ]; then
-                readabilityWords=$(vale ls-metrics "$file" | grep '"words"' | sed 's/[^0-9]*//g')
-                readabilitySentences=$(vale ls-metrics "$file" | grep '"sentences"' | sed 's/[^0-9]*//g')
-                readabilitySyllables=$(vale ls-metrics "$file" | grep '"syllables"' | sed 's/[^0-9]*//g')
+            readabilityWords=$(vale ls-metrics "$file" | grep '"words"' | sed 's/[^0-9]*//g')
+            readabilitySentences=$(vale ls-metrics "$file" | grep '"sentences"' | sed 's/[^0-9]*//g')
+            readabilitySyllables=$(vale ls-metrics "$file" | grep '"syllables"' | sed 's/[^0-9]*//g')
         fi
     done
 
@@ -37,8 +38,9 @@ else
 
     # calculate mean number of words
     if [ "$files" -ge 1 ]; then
-        meanval=$(( readabilityWords / files))
-    else meanval=$readabilityWords
+        meanval=$((readabilityWords / files))
+    else
+        meanval=$readabilityWords
     fi
 
     readabilityAverage=$(echo "scale=2; 0.39 * ($readabilityWords / $readabilitySentences) + (11.8 * ($readabilitySyllables / $readabilityWords)) - 15.59" | bc)
@@ -49,7 +51,7 @@ else
     # value below 8 is considered readable
     if [ "$readabilityAverageInt" -lt 8 ]; then
         readable=true
-    else 
+    else
         readable=false
     fi
 
@@ -61,4 +63,4 @@ else
     echo -e "\taverage word count: $meanval"
     echo -e "\treadability: $readabilityAverage"
     echo -e "\treadable: $readable"
-fi
+fi

sp-files/.sphinx/spellingcheck.yaml

@@ -1,30 +1,30 @@
 matrix:
-- name: rST files
-  aspell:
-    lang: en
-    d: en_GB
-  dictionary:
-    wordlists:
-    - .sphinx/.wordlist.txt
-    - .custom_wordlist.txt
-    output: .sphinx/.wordlist.dic
-  sources:
-  - _build/**/*.html
-  pipeline:
-  - pyspelling.filters.html:
-      comments: false
-      attributes:
-      - title
-      - alt
-      ignores:
-      - code
-      - pre
-      - spellexception
-      - link
-      - title
-      - div.relatedlinks
-      - strong.command
-      - div.visually-hidden
-      - img
-      - a.p-navigation__link
-      - a.contributor
+  - name: rST files
+    aspell:
+      lang: en
+      d: en_GB
+    dictionary:
+      wordlists:
+        - .sphinx/.wordlist.txt
+        - .custom_wordlist.txt
+      output: .sphinx/.wordlist.dic
+    sources:
+      - _build/**/*.html
+    pipeline:
+      - pyspelling.filters.html:
+          comments: false
+          attributes:
+            - title
+            - alt
+          ignores:
+            - code
+            - pre
+            - spellexception
+            - link
+            - title
+            - div.relatedlinks
+            - strong.command
+            - div.visually-hidden
+            - img
+            - a.p-navigation__link
+            - a.contributor