Add Unit Testing

.github/workflows/ci.yml

@@ -1,46 +1,79 @@
 name: CI
 
 on:
-  push:
-    branches:
-      - master
   pull_request:
-    branches:
-      - '*'
+  push:
+  schedule:
+    - cron: '0 0/2 * * *'
 
 jobs:
   build:
+    if: endsWith(github.head_ref || github.ref_name, '.changes') == false
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ['3.7', '3.8', '3.9']
+        python: ['3.7', '3.8', '3.9', '3.10', '3.11']
       fail-fast: false
 
+    permissions:
+      contents: write
+
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
 
-    - uses: actions/setup-python@v2
+    - uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python }}
 
+    - name: Install tools
+      run: |
+        sudo apt -y install libxml2-utils
+
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install -r requirements.txt
+        pip install -r test/unit/requirements.txt
         pip install .
 
-    - name: Build test/
+    - name: Build Test
       run: |
-        cd test && make html SPHINXOPTS='-W'
+        cd test/must-build && make html SPHINXOPTS='-W'
 
     - name: Build Test with toc show_parents=hide
       run: |
-        cd test && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=hide'
+        cd test/must-build && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=hide'
 
     - name: Build Test with toc show_parents=domain
       run: |
-        cd test && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=domain'
+        cd test/must-build && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=domain'
 
     - name: Build Test with toc show_parents=all
       run: |
-        cd test && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=all'
+        cd test/must-build && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=all'
+
+    - name: Run Unit Testing
+      run: |
+        cd test/unit
+        find . -name '*.html' -exec rm {} \;
+        make html SPHINXOPTS='-W'
+        (cd _build/html && find . -name '*.html' -exec sh -c 'xmllint {} --xpath '"'"'//div[@role="main"]'"'"' | xmllint --format - > ../../{}' \;)
+        rm genindex.html index.html search.html php-modindex.html
+
+    - name: Diff Unit Outputs
+      run: |
+        cd test/unit
+        rm -r _build
+        git add . -N && git diff --exit-code
+
+    - name: Push Unit Changes
+      if: failure()
+      uses: stefanzweifel/git-auto-commit-action@v4
+      with:
+        branch: ${{ github.head_ref || github.ref_name }}.changes
+        create_branch: true
+        push_options: '--force'
+        commit_message: Unit Changes
+        commit_user_name: Bot
+        commit_user_email: bot@example.com
+        commit_author: Bot <bot@example.com>

.github/workflows/doc.yml

@@ -21,8 +21,8 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  # Build job
   build:
+    if: github.repository_owner == 'markstory'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -35,15 +35,14 @@ jobs:
         id: pages
         uses: actions/configure-pages@v3
 
-      - name: Build doct
+      - name: Build doc
         run: make -C doc html
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v1
         with:
           path: doc/_build/html
 
-  # Deployment job
   deploy:
     environment:
       name: github-pages

.gitignore

@@ -1,7 +1,8 @@
 dist/
 build/
 doc/_build
-test/_build
+test/must-build/_build
+test/unit/_build
 *.pyc
 *.egg-info
 .DS_Store

doc/conf.py

@@ -120,7 +120,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

test/conf.py → test/must-build/conf.py

@@ -120,7 +120,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

test/unit/Makefile

@@ -0,0 +1,130 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/sphinxcontrib-rubydomain-acceptancetest.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/sphinxcontrib-rubydomain-acceptancetest.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/sphinxcontrib-rubydomain-acceptancetest"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/sphinxcontrib-rubydomain-acceptancetest"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+latexpdf: latex
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

test/unit/conf.py

@@ -0,0 +1,17 @@
+import sys, os
+
+sys.path.append(os.path.abspath('..'))
+
+extensions = [
+    'sphinxcontrib.phpdomain',
+    'myst_parser',
+]
+
+myst_enable_extensions = ['colon_fence']
+
+source_suffix = '.rst'
+master_doc = 'index'
+
+exclude_patterns = ['_build']
+
+html_theme = 'default'

test/unit/index.md

@@ -0,0 +1,7 @@
+# Test: Build all files
+
+:::{toctree}
+:glob:
+
+**
+:::