pkgs/sagemath-doc-{html,pdf}

.ci/write-dockerfile.sh

@@ -277,7 +277,6 @@ FROM with-system-packages AS bootstrapped
 RUN rm -rf /new /sage/.git
 $ADD Makefile VERSION.txt COPYING.txt condarc.yml README.md bootstrap bootstrap-conda configure.ac sage .homebrew-build-env tox.ini Pipfile.m4 .gitignore /new/
 $ADD config/config.rpath /new/config/config.rpath
-$ADD src/doc/bootstrap /new/src/doc/bootstrap
 $ADD src/bin /new/src/bin
 $ADD src/Pipfile.m4 src/pyproject.toml src/requirements.txt.m4 src/setup.cfg.m4 src/VERSION.txt /new/src/
 $ADD m4 /new/m4

.github/workflows/doc-build-pdf.yml

@@ -2,7 +2,7 @@ name: Build documentation (PDF)
 
 on:
   pull_request:
-  push:
+  merge_group:
   workflow_dispatch:
     # Allow to run manually
     inputs:

.github/workflows/doc-build.yml

@@ -39,6 +39,8 @@ env:
   FROM_DOCKER_TARGET:     "with-targets"
   FROM_DOCKER_TAG:        ${{ github.event.inputs.docker_tag || 'dev'}}
   EXTRA_CONFIGURE_ARGS:   --enable-fat-binary
+  # For deployment of the sagemath_doc_... wheels to PyPI
+  CAN_DEPLOY:             ${{ secrets.SAGEMATH_PYPI_API_TOKEN != '' }}
 
 jobs:
   build-doc:
@@ -164,6 +166,10 @@ jobs:
              git add -A && git commit --quiet -m 'old')
           fi
 
+      #
+      # On PRs and pushes to branches
+      #
+
       - name: Build doc
         id: docbuild
         if: (success() || failure()) && steps.worktree.outcome == 'success' && !startsWith(github.ref, 'refs/tags/')
@@ -221,7 +227,7 @@ jobs:
 
       - name: Upload doc
         id: upload
-        if: (success() || failure()) && steps.copy.outcome == 'success'
+        if: (success() || failure()) && steps.copy.outcome == 'success'  && !startsWith(github.ref, 'refs/tags/')
         uses: actions/upload-artifact@v4
         with:
           name: doc
@@ -243,8 +249,8 @@ jobs:
           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
+          ./config.status && make SAGE_WHEELS=yes SAGE_EDITABLE=no sagemath_doc_html-no-deps sagemath_doc_pdf-no-deps
+          (cd venv/var/lib/sage/ && zip /sage/sagemath_doc_wheels.zip wheels/sagemath_doc*.whl)
         shell: sh .ci/docker-exec-script.sh BUILD /sage {0}
 
       - name: Copy live doc
@@ -257,6 +263,8 @@ jobs:
           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
           zip -r livedoc.zip livedoc
+          docker cp BUILD:/sage/sagemath_doc_wheels.zip .
+          unzip sagemath_doc_wheels.zip
 
       - name: Upload live doc
         if: (success() || failure()) && steps.copylivedoc.outcome == 'success'
@@ -265,3 +273,19 @@ jobs:
           name: livedoc
           path: livedoc.zip
 
+      - name: Upload sagemath-doc wheels
+        id: uploaddocwheels
+        if: (success() || failure()) && steps.buildlivedoc.outcome == 'success'
+        uses: actions/upload-artifact@v4
+        with:
+          name: sagemath_doc_wheels
+          path: sagemath_doc_wheels.zip
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        if: (success() || failure()) && steps.buildlivedoc.outcome == 'success' && env.CAN_DEPLOY == 'true'
+        with:
+          user: __token__
+          password: ${{ secrets.SAGEMATH_PYPI_API_TOKEN }}
+          packages-dir: wheels/
+          skip-existing: true
+          verbose: true

.gitignore

@@ -200,6 +200,7 @@ build/pkgs/wheel/version_requirements.txt
 
 # Generated files in the top-level source trees
 /pkgs/*/build
+/pkgs/*/.mesonpy-*
 /pkgs/*/dist
 /pkgs/*/MANIFEST
 /pkgs/*/*.egg-info
@@ -235,6 +236,7 @@ build/pkgs/wheel/version_requirements.txt
 /pkgs/sagemath-sirocco/pyproject.toml
 /pkgs/sagemath-tdlib/pyproject.toml
 /pkgs/sagemath-categories/pyproject.toml
+/pkgs/sagemath-doc-*/pyproject.toml
 /pkgs/sagemath-environment/pyproject.toml
 /pkgs/sagemath-repl/pyproject.toml
 /pkgs/sagemath-objects/requirements*.txt

Makefile

@@ -366,7 +366,7 @@ SPKG_INFO_DEPENDENCIES =							\
 	build/pkgs/*/version_requirements.txt build/pkgs/*/package-version.txt	\
 	build/pkgs/*/distros/*.txt
 
-configure: bootstrap src/doc/bootstrap $(CONFIGURE_DEPENDENCIES) $(SPKG_INFO_DEPENDENCIES)
+configure: bootstrap $(CONFIGURE_DEPENDENCIES) $(SPKG_INFO_DEPENDENCIES)
 	./bootstrap -d
 
 install: all

build/make/Makefile.in

@@ -58,6 +58,8 @@ SAGE_SPKG_OPTIONS = @SAGE_SPKG_OPTIONS@
 # set to empty if --disable-doc is used
 SAGE_DOCS = @SAGE_DOCS@
 SAGE_DOCS_DISABLED_MESSAGE = This Sage build is configured with "configure --disable-doc", so building the documentation will not work.
+SAGE_VENV_DOCS = @SAGE_VENV_DOCS@
+SAGE_VENV_DOCS_DISABLED_MESSAGE = This Sage build is configured with "configure --disable-doc", so building the documentation will not work.
 
 # Where the Sage distribution installs Python packages.
 # This can be overridden by 'make SAGE_VENV=/some/venv'.
@@ -148,11 +150,14 @@ PYPI_WHEEL_PACKAGES = $(PYPI_NOARCH_WHEEL_PACKAGES) \
 	sagemath_sirocco			\
 	sagemath_meataxe
 
-# sage_docbuild is here, not in PYPI_WHEEL_PACKAGES, because it depends on sagelib
+# sage_docbuild is here, not in PYPI_WHEEL_PACKAGES, because it depends on sagelib.
+# This can be changed when we have separate 'dependencies_build' files.
 WHEEL_PACKAGES = $(PYPI_WHEEL_PACKAGES)		\
 	sage_conf				\
 	sagelib					\
-	sage_docbuild
+	sage_docbuild				\
+	sagemath_doc_html			\
+	sagemath_doc_pdf
 
 # Packages for which build sdists for PyPI
 PYPI_SDIST_PACKAGES = $(WHEEL_PACKAGES)
@@ -772,7 +777,7 @@ $(1)-uninstall: $(1)-$(4)-uninstall
 
 $(1)-clean: $(1)-uninstall
 
-$(1)-sdist: FORCE python_build sage_setup cython
+$(1)-sdist: FORCE python_build sage_setup cython meson_python
 	$(AM_V_at) cd '$$(SAGE_ROOT)' && \
 		. '$$(SAGE_ROOT)/src/bin/sage-src-env-config' && \
 		. '$$(SAGE_ROOT)/src/bin/sage-env-config' && \

build/pkgs/sagemath_doc_html/bootstrap

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+
+########################################################################
+# Regenerate auto-generated files, using information in SAGE_ROOT/build/
+#
+# This script is run by SAGE_ROOT/bootstrap as part of the bootstrapping phase
+# (before configure, before creating source distributions).
+#
+# The BOOTSTRAP_QUIET variable is set by the top-level
+# bootstrap script and controls how verbose we are.
+########################################################################
+
+set -e
+
+if [ -z "$SAGE_ROOT" ]; then
+    echo Please run the top-level bootstrap script of the Sage distribution.
+    exit 1
+fi
+
+./bootstrap_m4
+
+cd "$SAGE_ROOT"
+
+OUTPUT_DIR="src/doc/en/installation"
+mkdir -p "$OUTPUT_DIR"
+
+shopt -s extglob
+
+RECOMMENDED_SPKG_PATTERN="@(_recommended$(for a in $(head -n 1 build/pkgs/_recommended/dependencies); do echo -n "|"$a; done))"
+DEVELOP_SPKG_PATTERN="@(_develop$(for a in $(head -n 1 build/pkgs/_develop/dependencies); do echo -n "|"$a; done))"
+
+for SYSTEM in arch debian fedora homebrew opensuse void; do
+    SYSTEM_PACKAGES=
+    OPTIONAL_SYSTEM_PACKAGES=
+    SAGELIB_SYSTEM_PACKAGES=
+    SAGELIB_OPTIONAL_SYSTEM_PACKAGES=
+    RECOMMENDED_SYSTEM_PACKAGES=
+    DEVELOP_SYSTEM_PACKAGES=
+    for PKG_BASE in $(sage-package list --has-file distros/$SYSTEM.txt); do
+                PKG_SCRIPTS=build/pkgs/$PKG_BASE
+                PKG_TYPE=$(cat $PKG_SCRIPTS/type)
+                PKG_SYSTEM_PACKAGES=$(sage-get-system-packages $SYSTEM $PKG_BASE)
+                if [ -n "PKG_SYSTEM_PACKAGES" ]; then
+                    if [ -f $PKG_SCRIPTS/spkg-configure.m4 ]; then
+                       case "$PKG_BASE:$PKG_TYPE" in
+                           *:standard)
+                               SYSTEM_PACKAGES+=" $PKG_SYSTEM_PACKAGES"
+                               ;;
+                           $DEVELOP_SPKG_PATTERN:*)
+                               DEVELOP_SYSTEM_PACKAGES+=" $PKG_SYSTEM_PACKAGES"
+                               ;;
+                           $RECOMMENDED_SPKG_PATTERN:*)
+                               RECOMMENDED_SYSTEM_PACKAGES+=" $PKG_SYSTEM_PACKAGES"
+                               ;;
+                           *)
+                               OPTIONAL_SYSTEM_PACKAGES+=" $PKG_SYSTEM_PACKAGES"
+                               ;;
+                       esac
+                    else
+                        case "$PKG_BASE:$PKG_TYPE" in
+                           $DEVELOP_SPKG_PATTERN:*)
+                               DEVELOP_SYSTEM_PACKAGES+=" $PKG_SYSTEM_PACKAGES"
+                               ;;
+                            *:standard)
+                                SAGELIB_SYSTEM_PACKAGES+=" $PKG_SYSTEM_PACKAGES"
+                                ;;
+                            *)
+                                SAGELIB_OPTIONAL_SYSTEM_PACKAGES+=" $PKG_SYSTEM_PACKAGES"
+                                ;;
+                        esac
+                    fi
+                fi
+    done
+
+    if [ "${BOOTSTRAP_QUIET}" = "no" ]; then
+        echo >&2 $0:$LINENO: installing "$OUTPUT_DIR"/$SYSTEM"*.txt"
+    fi
+    echo "$(sage-print-system-package-command $SYSTEM --prompt --wrap --sudo install $(echo $(echo $SYSTEM_PACKAGES | xargs -n 1 echo | sort | uniq)))" > "$OUTPUT_DIR"/$SYSTEM.txt
+    echo "$(sage-print-system-package-command $SYSTEM --prompt --wrap --sudo install $(echo $(echo $OPTIONAL_SYSTEM_PACKAGES | xargs -n 1 echo | sort | uniq)))" > "$OUTPUT_DIR"/$SYSTEM-optional.txt
+    echo "$(sage-print-system-package-command $SYSTEM --prompt --wrap --sudo install $(echo $(echo $RECOMMENDED_SYSTEM_PACKAGES | xargs -n 1 echo | sort | uniq)))" > "$OUTPUT_DIR"/$SYSTEM-recommended.txt
+    echo "$(sage-print-system-package-command $SYSTEM --prompt --wrap --sudo install $(echo $(echo $DEVELOP_SYSTEM_PACKAGES | xargs -n 1 echo | sort | uniq)))" > "$OUTPUT_DIR"/$SYSTEM-develop.txt
+done
+
+OUTPUT_DIR="src/doc/en/reference/spkg"
+mkdir -p "$OUTPUT_DIR"
+if [ "${BOOTSTRAP_QUIET}" = "no" ]; then
+    echo >&2 $0:$LINENO: installing "$OUTPUT_DIR"/"*.rst"
+fi
+(cat <<EOF
+Mathematics
+~~~~~~~~~~~
+
+EOF
+for PKG_BASE in $(sage-package list --has-file SPKG.rst --has-file math :standard: | grep -v '^sagemath_'); do
+    echo "* :ref:\`spkg_$PKG_BASE\`"
+done
+cat <<EOF
+
+Front-end, graphics, document preparation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+EOF
+for PKG_BASE in $(sage-package list --has-file SPKG.rst --no-file math --has-file front-end :standard: | grep -v '^sagemath_'); do
+    echo "* :ref:\`spkg_$PKG_BASE\`"
+done
+cat <<EOF
+
+Other dependencies
+~~~~~~~~~~~~~~~~~~
+
+EOF
+for PKG_BASE in $(sage-package list --has-file SPKG.rst --no-file math --no-file front-end :standard: | grep -v '^sagemath_'); do
+    echo "* :ref:\`spkg_$PKG_BASE\`"
+done) > "$OUTPUT_DIR"/index_standard.rst
+(cat <<EOF
+Mathematics
+~~~~~~~~~~~
+
+EOF
+for PKG_BASE in $(sage-package list --has-file SPKG.rst --has-file math :optional: | grep -v '^sagemath_'); do
+    echo "* :ref:\`spkg_$PKG_BASE\`"
+done
+cat <<EOF
+
+Front-end, graphics, document preparation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+EOF
+for PKG_BASE in $(sage-package list --has-file SPKG.rst --no-file math --has-file front-end :optional: | grep -v '^sagemath_'); do
+    echo "* :ref:\`spkg_$PKG_BASE\`"
+done
+cat <<EOF
+
+Other dependencies
+~~~~~~~~~~~~~~~~~~
+
+EOF
+for PKG_BASE in $(sage-package list --has-file SPKG.rst --no-file math --no-file front-end :optional: | grep -v '^sagemath_'); do
+    echo "* :ref:\`spkg_$PKG_BASE\`"
+done) > "$OUTPUT_DIR"/index_optional.rst
+for PKG_BASE in $(sage-package list --has-file SPKG.rst | grep '^sagemath_'); do
+    echo "* :ref:\`spkg_$PKG_BASE\`"
+done > "$OUTPUT_DIR"/index_sagemath.rst
+(cat <<EOF
+Mathematics
+~~~~~~~~~~~
+
+EOF
+for PKG_BASE in $(sage-package list --has-file SPKG.rst --has-file math :experimental: | grep -v '^sagemath_'); do
+    echo "* :ref:\`spkg_$PKG_BASE\`"
+done
+
+cat <<EOF
+
+Other dependencies
+~~~~~~~~~~~~~~~~~~
+
+EOF
+for PKG_BASE in $(sage-package list --has-file SPKG.rst --no-file math :experimental: | grep -v '^sagemath_'); do
+    echo "* :ref:\`spkg_$PKG_BASE\`"
+done) > "$OUTPUT_DIR"/index_experimental.rst
+(cat <<EOF
+
+Details of external packages
+============================
+
+Packages are in alphabetical order.
+
+.. default-role:: code
+
+.. toctree::
+   :maxdepth: 1
+
+EOF
+for PKG_BASE in $(sage-package list --has-file SPKG.rst); do
+    echo "   $PKG_BASE"
+done
+cat <<EOF
+
+.. default-role::
+
+EOF
+) > "$OUTPUT_DIR"/index_alph.rst
+sage-package list --has-file SPKG.rst | OUTPUT_DIR=$OUTPUT_DIR OUTPUT_RST=1 xargs -P 99 -n 1 sage-spkg-info

build/pkgs/sagemath_doc_html/bootstrap_m4

@@ -0,0 +1 @@
+../sagelib/bootstrap

build/pkgs/sagemath_doc_html/dependencies

@@ -1,4 +1,4 @@
-sagelib sphinx sphinx_copybutton sphinx_inline_tabs pplpy_doc | $(SAGERUNTIME) maxima networkx scipy sympy matplotlib pillow mathjax mpmath ipykernel jupyter_client conway_polynomials tachyon ipywidgets sage_docbuild elliptic_curves furo fpylll graphs
+sagelib sphinx sphinx_copybutton sphinx_inline_tabs pplpy_doc | $(SAGERUNTIME) maxima networkx scipy sympy matplotlib pillow mathjax mpmath ipykernel jupyter_client conway_polynomials tachyon ipywidgets sage_docbuild elliptic_curves furo fpylll graphs meson_python
 
 # Building the documentation has many dependencies, because all
 # documented modules are imported and because we use matplotlib to

build/pkgs/sagemath_doc_html/package-version.txt

@@ -0,0 +1 @@
+src/VERSION.txt

build/pkgs/sagemath_doc_html/spkg-install.in

@@ -0,0 +1,20 @@
+cd src
+
+# Needed because we have trees.txt, which directs us to $SAGE_LOCAL/...
+export PIP_FIND_LINKS=$SAGE_VENV/var/lib/sage/wheels
+
+if [ "$SAGE_EDITABLE" = yes ]; then
+    # Editables 0.5 does not map non-package data files
+    # https://editables.readthedocs.io/en/latest/use-cases.html#mapping-non-python-directories-or-files
+    mkdir -p ${SAGE_DESTDIR}${SAGE_INST_LOCAL}/share/doc/sage
+    sdh_pip_editable_install .
+    # We expect a subdirectory like build/cp312.
+    # Use 'find -newer' to use the one just created/modified by the editable build.
+    find $(pwd -P)/build -maxdepth 1 -name "cp*" -newer ${SAGE_DESTDIR}${SAGE_INST_LOCAL} -exec \
+         ln -svf {}/html {}/index.html ${SAGE_DESTDIR}${SAGE_INST_LOCAL}/share/doc/sage/ \;
+    if [ "$SAGE_WHEELS" = yes ]; then
+        sdh_build_and_store_wheel --no-build-isolation .
+    fi
+else
+    sdh_pip_install --no-build-isolation .
+fi

build/pkgs/sagemath_doc_html/spkg-legacy-uninstall

@@ -0,0 +1,4 @@
+#! /usr/bin/env bash
+if [ -d "$SAGE_DOC" ]; then
+    rm -rf "$SAGE_DOC"/doctrees "$SAGE_DOC"/inventory "$SAGE_DOC"/html "$SAGE_DOC"/*.html
+fi

build/pkgs/sagemath_doc_html/spkg-postinst.in

@@ -0,0 +1,7 @@
+mkdir -p "${SAGE_DOC}"
+cd "${SAGE_INST_LOCAL}/share/doc/sage"
+for a in *; do
+    if [ -e "$a" -a ! -e "${SAGE_DOC}/$a" ]; then
+        ln -sf "${SAGE_INST_LOCAL}/share/doc/sage/$a" "${SAGE_DOC}/$a"
+    fi
+done