Add tests for the starter pack

.github/workflows/test-starter-pack.yml

@@ -0,0 +1,69 @@
+# This workflow runs the init.sh script to test setting up
+# the starter pack.
+# You shouldn't run this workflow on any repos that use the
+# starter pack.
+
+name: Test starter pack
+
+on:
+  - pull_request
+  - push
+
+jobs:
+  test-root:
+    name: Test in root folder
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+      - name: Run init and build
+        run: sp-tests/run-init-and-build.sh
+      - name: Add some files, build, and test
+        run: sp-tests/add-files-and-build.sh
+      - name: Run inclusive language check
+        if: success() || failure()
+        run: sp-tests/check-inclusive-language.sh
+      - name: Run link check
+        if: success() || failure()
+        run: sp-tests/check-links.sh
+      - name: Run spelling check
+        if: success() || failure()
+        run: sp-tests/check-spelling.sh
+      - name: Run styleguide check (expected to fail)
+        continue-on-error: true
+        if: success() || failure()
+        run: sp-tests/check-styleguide.sh
+      - name: Run accessibility check
+        if: success() || failure()
+        run: sp-tests/check-accessibility.sh
+      - name: Clean up
+        if: success() || failure()
+        run: sp-tests/clean-up.sh
+  test-docs:
+    name: Test on docs folder
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+      - name: Run init and build
+        run: sp-tests/run-init-and-build.sh docs
+      - name: Add some files, build, and test
+        run: sp-tests/add-files-and-build.sh docs
+      - name: Run inclusive language check
+        if: success() || failure()
+        run: sp-tests/check-inclusive-language.sh docs
+      - name: Run link check
+        if: success() || failure()
+        run: sp-tests/check-links.sh docs
+      - name: Run spelling check
+        if: success() || failure()
+        run: sp-tests/check-spelling.sh docs
+      - name: Run styleguide check (expected to fail)
+        continue-on-error: true
+        run: sp-tests/check-styleguide.sh docs
+      - name: Run accessibility check
+        if: success() || failure()
+        run: sp-tests/check-accessibility.sh docs
+      - name: Clean up
+        if: success() || failure()
+        run: sp-tests/clean-up.sh

.gitignore

@@ -0,0 +1 @@
+testdir

sp-files/.sphinx/get_vale_conf.py

@@ -20,10 +20,22 @@ def main():
         file.write(download.text)
         file.close()
 
+    if os.path.exists(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical"):
+        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")
     file = open(".sphinx/vale.ini", "w")
     file.write(config.text)
     file.close()
 
 if __name__ == "__main__":
-    main()
+    main()

sp-files/Makefile.sp

@@ -17,7 +17,7 @@ VENV          = $(VENVDIR)/bin/activate
 TARGET        = *
 ALLFILES      =  *.rst **/*.rst
 
-.PHONY: sp-full-help sp-woke-install sp-pa11y-install sp-install sp-run sp-html \
+.PHONY: sp-full-help sp-woke-install sp-spellcheck-install sp-pa11y-install sp-install sp-run sp-html \
         sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \
         sp-pa11y Makefile.sp sp-vale
 
@@ -44,6 +44,10 @@ sp-woke-install:
 	@type woke >/dev/null 2>&1 || \
             { echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
 
+sp-spellcheck-install:
+	@type aspell >/dev/null 2>&1 || \
+            { echo "Installing aspell... \n"; sudo apt-get install aspell aspell-en; }
+
 sp-pa11y-install:
 	@type $(PA11Y) >/dev/null 2>&1 || { \
 			echo "Installing \"pa11y\" from npm... \n"; \
@@ -77,7 +81,7 @@ sp-clean-doc:
 	git clean -fx "$(BUILDDIR)"
 	rm -rf $(SPHINXDIR)/.doctrees
 
-sp-spellcheck:
+sp-spellcheck: sp-spellcheck-install
 	. $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc)
 
 sp-spelling: sp-html sp-spellcheck

sp-files/conf.py

@@ -216,3 +216,7 @@
 .. role:: center
    :class: align-center
 '''
+
+# Workaround for https://github.com/canonical/canonical-sphinx/issues/34
+if not 'discourse_prefix' in html_context and 'discourse' in html_context:
+    html_context['discourse_prefix'] = html_context['discourse'] + '/t/'

sp-tests/add-files-and-build.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+set -ex
+
+source sp-tests/get-installation-directory.sh
+
+# Copy the test files
+cp sp-tests/testfiles/test-md.md testdir/$install_directory/
+cp sp-tests/testfiles/test-rst.rst testdir/$install_directory/
+
+# Include the files in the toctree
+if ! grep -Fxq "   test-md" testdir/$install_directory/index.rst
+then
+   echo "   test-md" >> testdir/$install_directory/index.rst
+   echo "   test-rst" >> testdir/$install_directory/index.rst
+fi
+
+# Build the documentation
+cd testdir/$install_directory
+make html
+
+# Test the output
+if ! grep -Fq "A documentation starter-pack" _build/test-md/index.html || \
+        ! grep -Fq "A documentation starter-pack" _build/test-rst/index.html
+then
+    echo "Related links don't work (in RST or Markdown)"
+    exit 1
+fi
+
+if ! grep -Fq "Open Documentation Hour" _build/test-md/index.html || \
+        ! grep -Fq "Open Documentation Hour" _build/test-rst/index.html
+then
+    echo "Discourse links don't work (in RST or Markdown)"
+    exit 1
+fi

sp-tests/check-accessibility.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -ex
+
+source sp-tests/get-installation-directory.sh
+
+# Test the documentation
+cd testdir/$install_directory
+make pa11y

sp-tests/check-inclusive-language.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -ex
+
+source sp-tests/get-installation-directory.sh
+
+# Test the documentation
+cd testdir/$install_directory
+make woke

sp-tests/check-links.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -ex
+
+source sp-tests/get-installation-directory.sh
+
+# Test the documentation
+cd testdir/$install_directory
+make linkcheck

sp-tests/check-spelling.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -ex
+
+source sp-tests/get-installation-directory.sh
+
+# Copy the custom wordlist
+cp sp-tests/testfiles/.custom_wordlist.txt testdir/$install_directory/
+
+# Test the documentation
+cd testdir/$install_directory
+make spelling

sp-tests/check-styleguide.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -ex
+
+source sp-tests/get-installation-directory.sh
+
+# Test the documentation
+cd testdir/$install_directory
+make vale

sp-tests/clean-up.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -ex
+
+# clean up
+rm -rf testdir

sp-tests/get-installation-directory.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -e
+
+# Determine installation directory
+while getopts d: flag
+do
+    case "${flag}" in
+        d) install_directory=${OPTARG};;
+    esac
+done
+
+if [ ! -n "$install_directory" ]; then
+    install_directory="."
+fi

sp-tests/run-init-and-build.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+set -ex
+
+source sp-tests/get-installation-directory.sh
+
+# Save current directory
+cwd=$(pwd)
+
+# Check if the testdir folder must be deleted first
+if test -d "testdir"; then
+    read -p "The \"testdir\" folder already exists. Delete the folder? (y/n) " deletefolder
+    if [ $deletefolder = "y" ]; then
+        rm -rf testdir
+    fi
+fi
+
+# Create a folder for testing
+mkdir testdir
+cd testdir
+git init
+
+# Copy the init script
+cp ../init.sh .
+chmod u+x init.sh
+
+# Run the init script
+./init.sh $install_directory
+
+# Make a first commit
+git add .
+git config user.email "[email protected]"
+git config user.name "Dummy user"
+git commit -m 'adding all files'
+
+# Build the documentation
+cd $install_directory
+make html

sp-tests/testfiles/.custom_wordlist.txt

@@ -0,0 +1,62 @@
+adipiscing
+aliqua
+amet
+arcu
+augue
+blandit
+congue
+consectetur
+Consectetur
+consequat
+cursus
+dolor
+dolore
+dui
+Dui
+eget
+eiusmod
+elit
+enim
+et
+eu
+faucibus
+habitant
+iaculis
+incididunt
+Ipsum
+labore
+lacus
+lectus
+leo
+libero
+lorem
+magna
+massa
+mattis
+mauris
+molestie
+nec
+Nibh
+nisl
+nulla
+nullam
+nunc
+Nunc
+odio
+ornare
+Ornare
+pellentesque
+pharetra
+phasellus
+porttitor
+rhoncus
+scelerisque
+sed
+sem
+sollicitudin
+tempor
+tincidunt
+Urna
+ut
+vestibulum
+viverra

sp-tests/testfiles/test-md.md

@@ -0,0 +1,6 @@
+---
+discourse: 42771
+relatedlinks: https://github.com/canonical/sphinx-docs-starter-pack
+---
+
+# Markdown test

sp-tests/testfiles/test-rst.rst

@@ -0,0 +1,5 @@
+:discourse: 42771
+:relatedlinks: https://github.com/canonical/sphinx-docs-starter-pack
+
+reST test
+=========