Merge pull request #80 from pmatulis/OVN-299-sync-with-starter-pack

docs: sync with starter pack - build files

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

@@ -1,63 +1,16 @@
-name: Automatic documentation checks
+name: Main Documentation Checks
 
 on:
   - push
   - pull_request
+  - workflow_dispatch
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  spellcheck:
-    name: Spelling check
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Install Aspell
-        run: |
-          sudo apt-get install aspell aspell-en
-
-      - name: Install the doc framework
-        working-directory: docs
-        run: |
-          make install
-
-      - name: Build docs and run spelling checker
-        working-directory: docs
-        run: |
-          make spelling
-
-  woke:
-    name: Inclusive language check
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: woke
-        uses: get-woke/woke-action@v0
-        with:
-          # Cause the check to fail on any broke rules
-          fail-on-error: true
-          workdir: docs
-          woke-args: "*.rst **/*.rst -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml"
-
-  linkcheck:
-    name: Link check
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Install the doc framework
-        working-directory: docs
-        run: |
-          make install
-
-      - name: Run linkchecker
-        working-directory: docs
-        run: |
-          make linkcheck
+  documentation-checks:
+    uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
+    with:
+      working-directory: 'docs'

docs/.gitignore

@@ -1,6 +1,7 @@
 /*env*/
 .sphinx/venv
 .sphinx/warnings.txt
+.sphinx/.doctrees
 .sphinx/.wordlist.dic
 _build
 .DS_Store

docs/Makefile

@@ -3,63 +3,128 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -c . -d .sphinx/.doctrees
 SPHINXBUILD   ?= sphinx-build
+SPHINXDIR     = .sphinx
 SOURCEDIR     = .
 BUILDDIR      = _build
-VENV          = .sphinx/venv/bin/activate
+VENVDIR       = $(SPHINXDIR)/venv
+VENV          = $(VENVDIR)/bin/activate
 
 
 # Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+help: $(VENVDIR)
+	@. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-install:
-	@echo "... setting up virtualenv"
-	python3 -m venv .sphinx/venv
-	. $(VENV); pip install --upgrade -r .sphinx/requirements.txt
+.PHONY: help
+
+# Explicit target avoids fall-through to the "Makefile" target.
+$(SPHINXDIR)/requirements.txt:
+	test -f $(SPHINXDIR)/requirements.txt
 
+# If requirements are updated, venv should be rebuilt and timestamped.
+$(VENVDIR): $(SPHINXDIR)/requirements.txt
+	@echo "... setting up virtualenv"
+	python3 -m venv $(VENVDIR)
+	. $(VENV); pip install --require-virtualenv \
+        --upgrade -r $(SPHINXDIR)/requirements.txt \
+        --log $(VENVDIR)/pip_install.log
+	@test ! -f $(VENVDIR)/pip_list.txt || \
+        mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
+	@. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
 	@echo "\n" \
-		"--------------------------------------------------------------- \n" \
-		"* watch, build and serve the documentation: make run \n" \
-                "* only build: make html \n" \
-                "* only serve: make serve \n" \
-                "* clean built doc files: make clean-doc \n" \
-                "* clean full environment: make clean \n" \
-		"* check spelling: make spelling \n" \
-                "* check inclusive language: make woke \n" \
-		"--------------------------------------------------------------- \n"
-run:
-	. $(VENV); sphinx-autobuild -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)"
-
-html:
-	. $(VENV); $(SPHINXBUILD) -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt
-
-epub:
-	. $(VENV); $(SPHINXBUILD) -c . -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt
-
-serve:
+        "--------------------------------------------------------------- \n" \
+        "* watch, build and serve the documentation: make run \n" \
+        "* only build: make html \n" \
+        "* only serve: make serve \n" \
+        "* clean built doc files: make clean-doc \n" \
+        "* clean full environment: make clean \n" \
+        "* check spelling: make spelling \n" \
+        "* check inclusive language: make woke \n" \
+        "* other possible targets: make <press TAB twice> \n" \
+        "--------------------------------------------------------------- \n"
+	@touch $(VENVDIR)
+
+
+woke-install:
+	@type woke >/dev/null 2>&1 || \
+        { echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
+
+.PHONY:  woke-install
+
+
+install: $(VENVDIR) woke-install
+
+.PHONY:  install
+
+
+run: install
+	. $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" \
+	$(SPHINXOPTS)
+
+.PHONY: run
+
+# Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
+html: install
+	. $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" \
+        -w .sphinx/warnings.txt $(SPHINXOPTS)
+
+.PHONY: html
+
+
+epub: install
+	. $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" \
+        -w .sphinx/warnings.txt $(SPHINXOPTS)
+
+.PHONY: epub
+
+
+serve: html
 	cd "$(BUILDDIR)"; python3 -m http.server 8000
 
+.PHONY: serve
+
+
 clean: clean-doc
-	rm -rf .sphinx/venv
+	@test ! -e "$(VENVDIR)" -o \
+        -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
+	rm -rf $(VENVDIR)
+	rm -rf .sphinx/.doctrees
+
+.PHONY: clean
+
 
 clean-doc:
 	git clean -fx "$(BUILDDIR)"
 
+.PHONY: clean-doc
+
+
 spelling: html
 	. $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml
 
-linkcheck:
-	. $(VENV) ; $(SPHINXBUILD) -c . -b linkcheck  "$(SOURCEDIR)" "$(BUILDDIR)"
+.PHONY: spelling
+
+
+linkcheck: install
+	. $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" \
+	$(SPHINXOPTS)
+
+.PHONY: linkcheck
 
-woke:
-	type woke >/dev/null 2>&1 || { snap install woke; exit 1; }
-	woke *.rst **/*.rst -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml
 
-.PHONY: help Makefile
+woke: woke-install
+	woke *.rst **/*.rst \
+		--exit-1-on-failure \
+        -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
+
+.PHONY: woke
+
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	. $(VENV); \
+        $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: Makefile