diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 614cef2a..1954ec14 100644 --- a/.readthedocs.yaml +++ b/.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 diff --git a/docs/Makefile b/docs/Makefile index a3e311fa..1bfac7b0 100644 --- a/docs/Makefile +++ b/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/* diff --git a/docs/generated/.gitignore b/docs/generated/.gitignore new file mode 100644 index 00000000..72e8ffc0 --- /dev/null +++ b/docs/generated/.gitignore @@ -0,0 +1 @@ +* diff --git a/docs/source/conf.py b/docs/source/conf.py index 4e3bbf3c..1a895a09 100644 --- a/docs/source/conf.py +++ b/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), diff --git a/docs/source/evaluation.md b/docs/source/evaluation.md index 285befd9..86119368 100644 --- a/docs/source/evaluation.md +++ b/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.