gh-39973: Migrate CI build-doc to Meson
    
<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes #12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes #12345". -->

Make it possible to build the documentation with meson via
```
meson compile -C builddir doc-html
```

For this a couple of changes was necessary in the docbuilder:
- Make `sage_docbuild` independent of `sage` so that meson can use
`sage_docbuild` during config time to construct all the docbuild targets
(otherwise one needs to first install sage, and then could configure the
docbuild)
- Properly handle input and output dirs for the docbuild, without
relying on magic sage env variables

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [ ] The title is concise and informative.
- [ ] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation and checked the documentation
preview.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->
    
URL: #39973
Reported by: Tobias Diez
Reviewer(s): Dima Pasechnik, Tobias Diez, user202729

Author: Release Manager

.github/workflows/doc-build.yml

@@ -16,117 +16,67 @@ on:
       - develop
   workflow_dispatch:
     # Allow to run manually
-    inputs:
-      platform:
-        description: 'Platform'
-        required: true
-        default: 'ubuntu-noble-standard'
-      docker_tag:
-        description: 'Docker tag'
-        required: true
-        default: 'dev'
 
 concurrency:
   # Cancel previous runs of this workflow for the same branch
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 env:
-  # Same as in build.yml
-  TOX_ENV:                "docker-${{ github.event.inputs.platform || 'ubuntu-noble-standard' }}-incremental"
-  BUILD_IMAGE:            "localhost:5000/${{ github.repository }}/sage-${{ github.event.inputs.platform || 'ubuntu-noble-standard' }}-with-targets:ci"
-  FROM_DOCKER_REPOSITORY: "ghcr.io/sagemath/sage/"
-  FROM_DOCKER_TARGET:     "with-targets"
-  FROM_DOCKER_TAG:        ${{ github.event.inputs.docker_tag || 'dev'}}
-  EXTRA_CONFIGURE_ARGS:   --enable-fat-binary
+  PYTHON_VERSION: 3.11
 
 jobs:
   build-doc:
     runs-on: ubuntu-latest
-    services:
-      # https://docs.docker.com/build/ci/github-actions/local-registry/
-      registry:
-        image: registry:2
-        ports:
-          - 5000:5000
     steps:
-      - name: Maximize build disk space
-        uses: easimon/maximize-build-space@v10
-        with:
-          # need space in /var for Docker images
-          root-reserve-mb:      30000
-          remove-dotnet:        true
-          remove-android:       true
-          remove-haskell:       true
-          remove-codeql:        true
-          remove-docker-images: true
       - name: Checkout
         uses: actions/checkout@v4
-      - name: Install test prerequisites
-        # From docker.yml
-        run: |
-          sudo DEBIAN_FRONTEND=noninteractive apt-get update
-          sudo DEBIAN_FRONTEND=noninteractive apt-get install tox
-          sudo apt-get clean
-          df -h
+
       - name: Merge CI fixes from sagemath/sage
         run: |
-          mkdir -p upstream
-          .github/workflows/merge-fixes.sh 2>&1 | tee upstream/ci_fixes.log
+          .github/workflows/merge-fixes.sh
         env:
           GH_TOKEN: ${{ github.token }}
-          SAGE_CI_FIXES_FROM_REPOSITORIES: ${{ vars.SAGE_CI_FIXES_FROM_REPOSITORIES }}
-
-      # Building
-
-      - name: Generate Dockerfile
-        # From docker.yml
-        run: |
-          tox -e ${{ env.TOX_ENV }}
-          cp .tox/${{ env.TOX_ENV }}/Dockerfile .
-        env:
-          # Only generate the Dockerfile, do not run 'docker build' here
-          DOCKER_TARGETS: ""
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+      - name: Cache conda packages
+        uses: actions/cache@v4
         with:
-          driver-opts: network=host
-
-      - name: Build Docker image
-        id: image
-        uses: docker/build-push-action@v6
+          path: ~/conda_pkgs_dir
+          key:
+            ${{ runner.os }}-conda-${{ hashFiles('environment-${{ env.PYTHON_VERSION }}-linux.yml') }}
+  
+      - name: Compiler cache
+        uses: hendrikmuhs/[email protected]
         with:
-          # push and load may not be set together at the moment
-          push:       true
-          load:       false
-          context:    .
-          tags:       ${{ env.BUILD_IMAGE }}
-          target:     with-targets
-          cache-from: type=gha
-          cache-to:   type=gha,mode=max
-          build-args: |
-            NUMPROC=6
-            USE_MAKEFLAGS=-k V=0 SAGE_NUM_THREADS=4 --output-sync=recurse
-            TARGETS_PRE=build/make/Makefile
-            TARGETS=ci-build-with-fallback
+          key: ${{ runner.os }}-meson-${{ env.PYTHON_VERSION }}
 
-      - name: Start container
-        id: container
-        # Try to continue when "exporting to GitHub Actions Cache" failed with timeout
+      - name: Setup Conda environment
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          # Disabled for now due to
+          # https://github.com/conda-incubator/setup-miniconda/issues/379
+          # miniforge-version: latest
+          use-mamba: true
+          channels: conda-forge
+          channel-priority: true
+          activate-environment: sage-dev
+          environment-file: environment-${{ env.PYTHON_VERSION }}-linux.yml
+        
+      - name: Build Sage
+        shell: bash -l {0}
         run: |
-          docker run --name BUILD -dit \
-                     --mount type=bind,src=$(pwd),dst=$(pwd) \
-                     --workdir $(pwd) \
-                     ${{ env.BUILD_IMAGE }} /bin/sh
+          export PATH="/usr/lib/ccache:/usr/local/opt/ccache/libexec:$PATH"
+          export CC="ccache $CC"
+          export CXX="ccache $CXX"
+          pip install --no-build-isolation --config-settings=builddir=builddir --editable . -v
 
       #
-      # On pull request and push to develop events
+      # For pull requests
       #
-
       - name: Get workflow run-id
         id: get_run_id
-        if: steps.container.outcome == 'success' && !startsWith(github.ref, 'refs/tags/') && github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request'
         run: |
           RESPONSE=$(curl -s -L \
             -H "Accept: application/vnd.github+json" \
@@ -149,6 +99,7 @@ jobs:
       - name: Store old doc
         id: worktree
         if: steps.download-doc.outcome == 'success'
+        shell: bash -l {0}
         run: |
           git config --global --add safe.directory $(pwd)
           git config --global user.email "[email protected]"
@@ -164,8 +115,8 @@ jobs:
             # mathjax path in old doc (regex)
             mathjax_path_from="[-./A-Za-z_]*/tex-chtml[.]js?v=[0-9a-f]*"
             # mathjax path in new doc
-            mathjax_path_to=$(docker exec -e SAGE_USE_CDNS=yes BUILD /sage/sage -python -c "from sage_docbuild.conf import mathjax_path; print(mathjax_path)")
-            new_version=$(docker exec BUILD cat src/VERSION.txt)
+            mathjax_path_to=$(SAGE_USE_CDNS=yes python -c "from src.sage_docbuild.conf import mathjax_path; print(mathjax_path)")
+            new_version=$(cat src/VERSION.txt)
             # Wipe out chronic diffs between old doc and new doc
             (cd doc && \
              find . -name "*.html" | xargs sed -i -e '/class="sidebar-brand-text"/ s/Sage [0-9a-z.]* /Sage '"$new_version"' /' \
@@ -185,20 +136,15 @@ jobs:
              git add -A && git commit --quiet -m 'old')
           fi
 
-      - name: Build doc
+      - name: Build documentation
         id: docbuild
-        if: steps.container.outcome == 'success' && !startsWith(github.ref, 'refs/tags/')
-        # Always non-incremental because of the concern that
-        # incremental docbuild may introduce broken links (inter-file references) though build succeeds
+        if: steps.worktree.outcome == 'success'
+        shell: bash -l {0}
         run: |
-          export GITHUB_REF=${{ github.ref }}
-          export PR_SHA=${{ github.event.pull_request.head.sha }}
-          export MAKE="make -j5 --output-sync=recurse" SAGE_NUM_THREADS=5
-          make doc-clean doc-uninstall
-          export SAGE_USE_CDNS=yes
-          export SAGE_DOCBUILD_OPTS="--include-tests-blocks"
-          ./config.status && make sagemath_doc_html-no-deps
-        shell: sh .github/workflows/docker-exec-script.sh BUILD /sage {0}
+          meson compile -C builddir doc-html
+        env:
+          SAGE_USE_CDNS: yes
+          SAGE_DOCBUILD_OPTS: "--include-tests-blocks"
 
       - name: Copy doc
         id: copy
@@ -209,12 +155,7 @@ jobs:
           if [ -d "doc/html" ]; then
               rm -rf doc/html
           fi
-          # Simpler "docker cp --follow-link ... doc" does not work
-          mkdir -p doc
-          mkdir -p temp
-          docker cp --follow-link BUILD:/sage/local/share/doc/sage/html temp
-          docker cp --follow-link BUILD:/sage/local/share/doc/sage/index.html temp
-          cp -r -L temp/* doc/
+          cp -r builddir/src/doc/* doc/
           # Check if we are on pull request event
           PR_NUMBER=""
           if [[ -n "$GITHUB_REF" ]]; then
@@ -275,30 +216,24 @@ jobs:
       - name: Build live doc
         id: buildlivedoc
         if: startsWith(github.ref, 'refs/tags/')
+        shell: bash -l {0}
         run: |
-          # Avoid running out of disk space
-          rm -rf upstream
-          export MAKE="make -j5 --output-sync=recurse" SAGE_NUM_THREADS=5
-          export PATH="build/bin:$PATH"
-          eval $(sage-print-system-package-command auto update)
-          eval $(sage-print-system-package-command auto --yes --no-install-recommends install zip)
-          eval $(sage-print-system-package-command auto --spkg --yes --no-install-recommends install git texlive texlive_luatex free_fonts xindy)
-          export SAGE_USE_CDNS=yes
-          export SAGE_LIVE_DOC=yes
-          export SAGE_JUPYTER_SERVER=binder:sagemath/sage-binder-env/dev
-          make doc-clean doc-uninstall
-          ./config.status && make sagemath_doc_html-no-deps sagemath_doc_pdf-no-deps
-        shell: sh .github/workflows/docker-exec-script.sh BUILD /sage {0}
+          meson compile -C builddir doc-html
+        env:
+          SAGE_USE_CDNS: yes
+          SAGE_LIVE_DOC: yes
+          SAGE_JUPYTER_SERVER: binder:sagemath/sage-binder-env/dev
+          SAGE_DOCBUILD_OPTS: "--include-tests-blocks"
 
       - name: Copy live doc
         id: copylivedoc
         if: steps.buildlivedoc.outcome == 'success'
         run: |
           mkdir -p ./livedoc
           # We copy everything to a local folder
-          docker cp --follow-link BUILD:/sage/local/share/doc/sage/html livedoc
-          docker cp --follow-link BUILD:/sage/local/share/doc/sage/pdf livedoc
-          docker cp --follow-link BUILD:/sage/local/share/doc/sage/index.html livedoc
+            cp -r builddir/src/doc/html livedoc/
+            cp -r builddir/src/doc/pdf livedoc/
+            cp builddir/src/doc/index.html livedoc/
           zip -r livedoc.zip livedoc
 
       - name: Upload live doc

environment-3.11-linux.yml

@@ -340,6 +340,7 @@ dependencies:
   - soupsieve=2.7=pyhd8ed1ab_0
   - sphinx=8.2.3=pyhd8ed1ab_0
   - sphinx-basic-ng=1.0.0b2=pyhd8ed1ab_3
+  - sphinx-copybutton=0.5.2=pyhd8ed1ab_1
   - sphinx-inline-tabs=2023.4.21=pyhd8ed1ab_1
   - sphinxcontrib-applehelp=2.0.0=pyhd8ed1ab_1
   - sphinxcontrib-devhelp=2.0.0=pyhd8ed1ab_1

meson.build

@@ -4,6 +4,7 @@ project(
   version: files('src/VERSION.txt'),
   license: 'GPL v3',
   default_options: ['c_std=c17', 'cpp_std=c++17', 'python.install_env=auto'],
+  meson_version: '>=1.2',
 )
 
 # Python module
@@ -215,4 +216,6 @@ for path in file_paths:
 ]
 run_command(create_files_command, check: true)
 
+root = meson.current_source_dir()
+
 subdir('src')

pyproject.toml

@@ -215,7 +215,8 @@ test = [
 ]
 docs = [
   "sphinx", 
-  "sphinx-inline-tabs", 
+  "sphinx-copybutton",
+  "sphinx-inline-tabs",
   "furo",
   "python-dateutil",
 ]
@@ -232,6 +233,7 @@ dev = [
   "conda-lock",
   "grayskull",
   "toml",
+  "uv",
 ]
 
 [tool.ruff]

src/build-docs.py

@@ -0,0 +1,4 @@
+from sage_docbuild.__main__ import main
+
+if __name__ == "__main__":
+    main()

src/doc/Makefile

@@ -40,7 +40,7 @@ doc-inventory-reference: doc-src
 	$(eval DOCS = $(shell sage --docbuild --all-documents reference))
 	@if [ -z "$(DOCS)" ]; then echo "Error: 'sage --docbuild --all-documents' failed"; exit 1; fi
 	$(eval BIBLIO = $(firstword $(DOCS)))
-	$(eval OTHER_DOCS = $(wordlist 2, 100, $(DOCS)))
+	$(eval OTHER_DOCS = $(filter-out reference_top, $(wordlist 2, 100, $(DOCS))))
 	$(MAKE) doc-inventory--$(subst /,-,$(BIBLIO))
 	$(MAKE) $(foreach doc, $(OTHER_DOCS), doc-inventory--$(subst /,-,$(doc)))
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-inventory--reference_top
@@ -51,7 +51,7 @@ doc-html-reference-sub: doc-inventory-reference
 	$(eval DOCS = $(shell sage --docbuild --all-documents reference))
 	@if [ -z "$(DOCS)" ]; then echo "Error: 'sage --docbuild --all-documents' failed"; exit 1; fi
 	$(eval BIBLIO = $(firstword $(DOCS)))
-	$(eval OTHER_DOCS = $(wordlist 2, 100, $(DOCS)))
+	$(eval OTHER_DOCS = $(filter-out reference_top, $(wordlist 2, 100, $(DOCS))))
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-html--$(subst /,-,$(BIBLIO))
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" $(foreach doc, $(OTHER_DOCS), doc-html--$(subst /,-,$(doc)))
 
@@ -63,7 +63,7 @@ doc-html-reference: doc-html-reference-sub
 doc-html-other: doc-html-reference
 	$(eval DOCS = $(shell sage --docbuild --all-documents all))
 	@if [ -z "$(DOCS)" ]; then echo "Error: 'sage --docbuild --all-documents' failed"; exit 1; fi
-	$(MAKE) $(foreach doc, $(wordlist 2, 100, $(DOCS)), doc-html--$(subst /,-,$(doc)))
+	$(MAKE) $(foreach doc, $(DOCS), doc-html--$(subst /,-,$(doc)))
 
 doc-html: doc-html-reference doc-html-other
 	SAGE_DOC=$$(sage --python -c "from sage.env import SAGE_DOC; print(SAGE_DOC)")
@@ -78,7 +78,7 @@ doc-pdf-reference: doc-inventory-reference
 	$(eval DOCS = $(shell sage --docbuild --all-documents reference))
 	@if [ -z "$(DOCS)" ]; then echo "Error: 'sage --docbuild --all-documents' failed"; exit 1; fi
 	$(eval BIBLIO = $(firstword $(DOCS)))
-	$(eval OTHER_DOCS = $(wordlist 2, 100, $(DOCS)))
+	$(eval OTHER_DOCS = $(filter-out reference_top, $(wordlist 2, 100, $(DOCS))))
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-pdf--$(subst /,-,$(BIBLIO))
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" $(foreach doc, $(OTHER_DOCS), doc-pdf--$(subst /,-,$(doc)))
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-pdf--reference_top
@@ -87,7 +87,7 @@ doc-pdf-reference: doc-inventory-reference
 doc-pdf-other: doc-pdf-reference
 	$(eval DOCS = $(shell sage --docbuild --all-documents all))
 	@if [ -z "$(DOCS)" ]; then echo "Error: 'sage --docbuild --all-documents' failed"; exit 1; fi
-	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" $(foreach doc, $(wordlist 2, 100, $(DOCS)), doc-pdf--$(subst /,-,$(doc)))
+	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" $(foreach doc, $(DOCS), doc-pdf--$(subst /,-,$(doc)))
 
 doc-pdf: doc-pdf-reference doc-pdf-other
 	SAGE_DOC=$$(sage --python -c "from sage.env import SAGE_DOC; print(SAGE_DOC)")

src/doc/bootstrap

@@ -18,6 +18,7 @@ if [ -z "$SAGE_ROOT" ]; then
 fi
 
 cd "$SAGE_ROOT"
+export PATH=build/bin:$PATH
 
 OUTPUT_DIR="src/doc/en/installation"
 mkdir -p "$OUTPUT_DIR"

src/doc/en/installation/meson.rst

@@ -172,7 +172,7 @@ To compile and install Sage in editable install, then just use:
         memory_allocator \
         "numpy >=1.25" \
         jinja2 \
-        setuptool
+        setuptools
     $ uv sync --frozen --inexact --no-build-isolation
 
 You can then start Sage from the command line with ``./sage``

src/doc/en/reference/conf_sub.py

@@ -11,9 +11,10 @@
 # serve to show the default.
 
 import os
-from sage.env import SAGE_DOC_SRC, SAGE_DOC
-from sage_docbuild.conf import release, exclude_patterns
+
+from sage.env import SAGE_DOC, SAGE_DOC_SRC
 from sage_docbuild.conf import *
+from sage_docbuild.conf import exclude_patterns
 
 # Add any paths that contain custom static files (such as style sheets),
 # relative to this directory to html_static_path. They are copied after the
@@ -26,7 +27,7 @@
 ref_out = os.path.join(SAGE_DOC, 'html', 'en', 'reference')
 
 # We use the main document's title, if we can find it.
-rst_file = open('index.rst', 'r')
+rst_file = open('index.rst', 'r', encoding='utf-8')
 rst_lines = rst_file.read().splitlines()
 rst_file.close()
 

src/doc/en/reference/repl/meson.build

@@ -0,0 +1,6 @@
+doc_src += custom_target(
+  'doc-src',
+  output: ['options.txt'],
+  command: [py, src / 'sage' / 'cli', '--help'],
+  capture: true,
+)