Use consistent path for downloadable satre.xlsx spreadsheet

.readthedocs.yaml

@@ -10,7 +10,10 @@ build:
     python: "3.11"
   jobs:
     pre_build:
-      - cd docs && make satrecsv
+      - cd docs && make satrecsv-copy
+    post_build:
+      # Check satre.xlsx was correctly copied
+      - cd docs && make check-satrecsv
 
 sphinx:
   configuration: docs/source/conf.py

docs/Makefile

@@ -12,14 +12,26 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile cleanall check-satrecsv
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-html: Makefile satrecsv
+# satrecsv is written to build/satrecsv and not READTHEDOCS_OUTPUT
+# because it's run by us in build.jobs.pre_build, not by readthedocs
+satrecsv-copy: satrecsv
+	cp -f build/satrecsv/satre.xlsx generated/
+
+html: Makefile satrecsv-copy
 	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-# satrecsv: Automatically handled by the catch-all target
+# If READTHEDOCS_OUTPUT is not set default to build
+OUTPUT_DIR := $(if $(READTHEDOCS_OUTPUT),$(READTHEDOCS_OUTPUT),build)
+# satre.xls is excluded from linkcheck, so check that it was copied to build/html
+check-satrecsv:
+	if [ ! -f "$(OUTPUT_DIR)/html/satre.xlsx" ]; then echo "ERROR: $(OUTPUT_DIR)/html/satre.xlsx not found"; exit 1; fi
+
+clean-all: clean
+	rm -f generated/*

docs/generated/.gitignore

@@ -0,0 +1 @@
+*

docs/source/conf.py

@@ -28,8 +28,18 @@
     "satrecsv",
 ]
 
+# The :download: role inserts a hash into the URL which varies between builds
+# html_extra_pathand attrs_inline allows us to use a consistent URL by copying
+# in satre.xlsx outside sphinx and treating it as an external URL
+# https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#customising-external-url-resolution
+html_extra_path = ["../generated/"]
+
+linkcheck_ignore = [
+    "satre.xlsx",
+]
+
 # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
-myst_enable_extensions = ["colon_fence", "deflist", "fieldlist"]
+myst_enable_extensions = ["attrs_inline", "colon_fence", "deflist", "fieldlist"]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),

docs/source/evaluation.md

@@ -60,4 +60,4 @@ If all pillars are met then the SATRE specification is met.
 
 ## Evaluation spreadsheet
 
-You can use this {download}`spreadsheet <../build/satrecsv/satre.xlsx>` as a template for your evaluation.
+You can use this [spreadsheet](satre.xlsx){.external} as a template for your evaluation.