build: Upgrade to Sphinx 7 (Same changes as cakephp#7641)

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
 
     - uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: 3.11
 
     - name: Install dependencies
       run: |

Dockerfile

@@ -1,27 +1,26 @@
-FROM debian:bullseye
+FROM debian:bookworm
 
 ENV DEBIAN_FRONTEND noninteractive
 
 LABEL Description="This image is used to create an environment to contribute to the cakephp/docs"
 
 RUN apt-get update && apt-get install -y \
+    build-essential \
     latexmk \
-    openjdk-8-jdk \
     php \
-    python3-pip \
+    python3-full \
     texlive-fonts-recommended \
     texlive-lang-all \
     texlive-latex-extra \
     texlive-latex-recommended \
   && apt-get clean \
   && rm -rf /var/lib/apt/lists/*
 
-COPY requirements.txt /tmp/
-RUN pip3 install -r /tmp/requirements.txt
+RUN python3 -m venv /tmp/venv
+ENV PATH="/tmp/venv/bin:$PATH"
 
-ADD https://github.com/w3c/epubcheck/releases/download/v4.2.2/epubcheck-4.2.2.zip /epubcheck/epubcheck.zip
-RUN unzip /epubcheck/epubcheck.zip -d /epubcheck \
-  && mv /epubcheck/epubcheck-4.2.2/* /epubcheck
+COPY requirements.txt /tmp/
+RUN pip install -r /tmp/requirements.txt
 
 WORKDIR /data
 VOLUME "/data"

Makefile

@@ -17,6 +17,7 @@ PDF_LANGS = en es fr pt
 DEST = website
 
 EPUB_ARGS =
+SPHINXOPTS =
 
 # Get path to theme directory to build static assets.
 THEME_DIR = $(shell python3 -c 'import os, cakephpsphinx; print(os.path.abspath(os.path.dirname(cakephpsphinx.__file__)))')
@@ -32,14 +33,13 @@ epub: $(foreach lang, $(LANGS), epub-$(lang))
 latex: $(foreach lang, $(PDF_LANGS), latex-$(lang))
 pdf: $(foreach lang, $(PDF_LANGS), pdf-$(lang))
 htmlhelp: $(foreach lang, $(LANGS), htmlhelp-$(lang))
-populate-index: $(foreach lang, $(LANGS), populate-index-$(lang))
 server: $(foreach lang, $(LANGS), server-$(lang))
 rebuild-index: $(foreach lang, $(LANGS), rebuild-index-$(lang))
 
 
 # Make the HTML version of the documentation with correctly nested language folders.
 html-%:
-	cd $* && make html
+	cd $* && make html SPHINXOPTS="$(SPHINXOPTS)"
 	make build/html/$*/_static/css/dist.css
 	make build/html/$*/_static/js/dist.js
 
@@ -58,13 +58,6 @@ pdf-%:
 server-%:
 	cd build/html/$* && python3 -m SimpleHTTPServer
 
-populate-index-%:
-	php scripts/populate_search_index.php --lang="$*" --host="$(ES_HOST_V2)"
-
-rebuild-index-%:
-	curl -XDELETE $(ES_HOST)/documentation/3-0-$*
-	php scripts/populate_search_index.php $* $(ES_HOST)
-
 epub-check-%: build/epub/$*
 	java -jar /epubcheck/epubcheck.jar build/epub/$*/CakePHP.epub $(EPUB_ARGS)
 

en/Makefile

@@ -8,13 +8,12 @@ PAPER         =
 BUILDDIR      = ../build
 CONFDIR       = ../config
 PYTHON        = python3
-LANG          = en
 SPHINX_LANG   = en
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$(LANG) -c $(CONFDIR) -D language=$(SPHINX_LANG) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$(SPHINX_LANG) -c $(CONFDIR) -D language=$(SPHINX_LANG) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 
@@ -41,9 +40,9 @@ clean:
 	-rm -rf $(BUILDDIR)/*
 
 html:
-	$(SPHINXBUILD) -b html -D "exclude_patterns=*-contents.rst" $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(LANG)
+	$(SPHINXBUILD) -b html -D "exclude_patterns=*-contents.rst" $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(LANG)."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(SPHINX_LANG)."
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -66,10 +65,10 @@ json:
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(LANG)
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(SPHINX_LANG)
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp/$(LANG)."
+	      ".hhp project file in $(BUILDDIR)/htmlhelp/$(SPHINX_LANG)."
 
 qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@@ -90,22 +89,22 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(SPHINX_LANG)."
 
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(LANG)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/$(LANG)."
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/$(SPHINX_LANG)."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(LANG)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(SPHINX_LANG)
 	@echo "Running LaTeX files through pdflatex..."
-	make -C $(BUILDDIR)/latex/$(LANG) all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/$(LANG)."
+	make -C $(BUILDDIR)/latex/$(SPHINX_LANG) all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/$(SPHINX_LANG)."
 
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text

es/Makefile

@@ -8,13 +8,12 @@ PAPER         =
 BUILDDIR      = ../build
 CONFDIR       = ../config
 PYTHON        = python3
-LANG          = es
 SPHINX_LANG   = es
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$(LANG) -c $(CONFDIR) -D language=$(SPHINX_LANG) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$(SPHINX_LANG) -c $(CONFDIR) -D language=$(SPHINX_LANG) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 
@@ -41,9 +40,9 @@ clean:
 	-rm -rf $(BUILDDIR)/*
 
 html:
-	$(SPHINXBUILD) -b html -D "exclude_patterns=*-contents.rst" $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(LANG)
+	$(SPHINXBUILD) -b html -D "exclude_patterns=*-contents.rst" $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(LANG)."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(SPHINX_LANG)."
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -66,10 +65,10 @@ json:
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(LANG)
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(SPHINX_LANG)
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp/$(LANG)."
+	      ".hhp project file in $(BUILDDIR)/htmlhelp/$(SPHINX_LANG)."
 
 qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@@ -90,22 +89,22 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(SPHINX_LANG)."
 
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(LANG)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/$(LANG)."
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/$(SPHINX_LANG)."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(LANG)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(SPHINX_LANG)
 	@echo "Running LaTeX files through pdflatex..."
-	make -C $(BUILDDIR)/latex/$(LANG) all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/$(LANG)."
+	make -C $(BUILDDIR)/latex/$(SPHINX_LANG) all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/$(SPHINX_LANG)."
 
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text

fr/Makefile

@@ -8,13 +8,12 @@ PAPER         =
 BUILDDIR      = ../build
 CONFDIR       = ../config
 PYTHON        = python3
-LANG          = fr
 SPHINX_LANG   = fr
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$(LANG) -c $(CONFDIR) -D language=$(SPHINX_LANG) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$(SPHINX_LANG) -c $(CONFDIR) -D language=$(SPHINX_LANG) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 
@@ -41,9 +40,9 @@ clean:
 	-rm -rf $(BUILDDIR)/*
 
 html:
-	$(SPHINXBUILD) -b html -D "exclude_patterns=*-contents.rst" $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(LANG)
+	$(SPHINXBUILD) -b html -D "exclude_patterns=*-contents.rst" $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(LANG)."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(SPHINX_LANG)."
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -66,10 +65,10 @@ json:
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(LANG)
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(SPHINX_LANG)
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp/$(LANG)."
+	      ".hhp project file in $(BUILDDIR)/htmlhelp/$(SPHINX_LANG)."
 
 qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@@ -90,22 +89,22 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(SPHINX_LANG)."
 
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(LANG)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/$(LANG)."
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/$(SPHINX_LANG)."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(LANG)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(SPHINX_LANG)
 	@echo "Running LaTeX files through pdflatex..."
-	make -C $(BUILDDIR)/latex/$(LANG) all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/$(LANG)."
+	make -C $(BUILDDIR)/latex/$(SPHINX_LANG) all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/$(SPHINX_LANG)."
 
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text

ja/Makefile

@@ -8,13 +8,12 @@ PAPER         =
 BUILDDIR      = ../build
 CONFDIR       = ../config
 PYTHON        = python3
-LANG          = ja
 SPHINX_LANG   = ja
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$(LANG) -c $(CONFDIR) -D language=$(SPHINX_LANG) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees/$(SPHINX_LANG) -c $(CONFDIR) -D language=$(SPHINX_LANG) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 
@@ -41,9 +40,9 @@ clean:
 	-rm -rf $(BUILDDIR)/*
 
 html:
-	$(SPHINXBUILD) -b html -D "exclude_patterns=*-contents.rst" $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(LANG)
+	$(SPHINXBUILD) -b html -D "exclude_patterns=*-contents.rst" $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(LANG)."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/$(SPHINX_LANG)."
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -66,10 +65,10 @@ json:
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(LANG)
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(SPHINX_LANG)
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp/$(LANG)."
+	      ".hhp project file in $(BUILDDIR)/htmlhelp/$(SPHINX_LANG)."
 
 qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@@ -90,22 +89,22 @@ devhelp:
 	@echo "# devhelp"
 
 epub:
-	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(LANG)
+	$(SPHINXBUILD) -b epub -D master_doc='epub-contents' $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(LANG)."
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub/$(SPHINX_LANG)."
 
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(LANG)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(SPHINX_LANG)
 	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/$(LANG)."
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/$(SPHINX_LANG)."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(LANG)
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(SPHINX_LANG)
 	@echo "Running LaTeX files through pdflatex..."
-	make -C $(BUILDDIR)/latex/$(LANG) all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/$(LANG)."
+	make -C $(BUILDDIR)/latex/$(SPHINX_LANG) all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex/$(SPHINX_LANG)."
 
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text