apacheGH-41430: [Docs] Use sphinxcontrib-mermaid instead of generatin…

…g images from .mmd

.github/workflows/docs.yml

@@ -32,12 +32,12 @@ env:
 jobs:
 
   complete:
-    name: AMD64 Ubuntu 22.04 Complete Documentation
+    name: AMD64 Debian 12 Complete Documentation
     runs-on: ubuntu-latest
     if: ${{ !contains(github.event.pull_request.title, 'WIP') }}
     timeout-minutes: 150
     env:
-      UBUNTU: "22.04"
+      JDK: 17
     steps:
       - name: Checkout Arrow
         uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4.0.0
@@ -50,8 +50,8 @@ jobs:
         uses: actions/cache@13aacd865c20de90d75de3b17ebe84f7a17d57d2 # v4.0.0
         with:
           path: .docker
-          key: ubuntu-docs-${{ hashFiles('cpp/**') }}
-          restore-keys: ubuntu-docs-
+          key: debian-docs-${{ hashFiles('cpp/**') }}
+          restore-keys: debian-docs-
       - name: Setup Python
         uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
         with:
@@ -73,4 +73,4 @@ jobs:
           ARCHERY_DOCKER_USER: ${{ secrets.DOCKERHUB_USER }}
           ARCHERY_DOCKER_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }}
         continue-on-error: true
-        run: archery docker push ubuntu-docs
+        run: archery docker push debian-docs

.github/workflows/docs_light.yml

@@ -31,7 +31,7 @@ on:
 
 permissions:
   contents: read
-  
+
 env:
   ARCHERY_DEBUG: 1
   ARCHERY_USE_DOCKER_CLI: 1

ci/conda_env_sphinx.txt

@@ -27,6 +27,7 @@ sphinx-autobuild
 sphinx-design
 sphinx-copybutton
 sphinxcontrib-jquery
+sphinxcontrib-mermaid
 sphinx==6.2
 # Requirement for doctest-cython
 # Needs upper pin of 0.3.0, see:

ci/docker/linux-apt-docs.dockerfile

@@ -21,18 +21,31 @@ FROM ${base}
 ARG r=4.4
 ARG jdk=8
 
-# See R install instructions at https://cloud.r-project.org/bin/linux/ubuntu/
+# See R install instructions at https://cloud.r-project.org/bin/linux/
 RUN apt-get update -y && \
     apt-get install -y \
-        dirmngr \
         apt-transport-https \
-        software-properties-common && \
-    wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc | \
-        tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc && \
-    add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu '$(lsb_release -cs)'-cran40/' && \
+        dirmngr \
+        gpg \
+        lsb-release && \
+    gpg --keyserver keyserver.ubuntu.com \
+        --recv-key 95C0FAF38DB3CCAD0C080A7BDC78B2DDEABC47B7 && \
+    gpg --export 95C0FAF38DB3CCAD0C080A7BDC78B2DDEABC47B7 | \
+        gpg --no-default-keyring \
+            --keyring /usr/share/keyrings/cran.gpg \
+            --import - && \
+    echo "deb [signed-by=/usr/share/keyrings/cran.gpg] https://cloud.r-project.org/bin/linux/$(lsb_release -is | tr 'A-Z' 'a-z') $(lsb_release -cs)-cran40/" | \
+        tee /etc/apt/sources.list.d/cran.list && \
+    if [ -f /etc/apt/sources.list.d/debian.sources ]; then \
+        sed -i \
+            -e 's/main$/main contrib non-free non-free-firmware/g' \
+            /etc/apt/sources.list.d/debian.sources; \
+    fi && \
+    apt-get update -y && \
     apt-get install -y --no-install-recommends \
         autoconf-archive \
         automake \
+        chromium \
         curl \
         doxygen \
         gi-docgen \
@@ -48,16 +61,20 @@ RUN apt-get update -y && \
         libxml2-dev \
         meson \
         ninja-build \
+        nodejs \
+        npm \
         nvidia-cuda-toolkit \
         openjdk-${jdk}-jdk-headless \
         pandoc \
         r-recommended=${r}* \
         r-base=${r}* \
         rsync \
         ruby-dev \
+        sudo \
         wget && \
     apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
+    rm -rf /var/lib/apt/lists/* && \
+    npm install -g yarn @mermaid-js/mermaid-cli
 
 ENV JAVA_HOME=/usr/lib/jvm/java-${jdk}-openjdk-amd64
 
@@ -68,20 +85,6 @@ RUN /arrow/ci/scripts/util_download_apache.sh \
 ENV PATH=/opt/apache-maven-${maven}/bin:$PATH
 RUN mvn -version
 
-ARG node=16
-RUN apt-get purge -y npm && \
-    apt-get autoremove -y --purge && \
-    wget -q -O - https://deb.nodesource.com/setup_${node}.x | bash - && \
-    apt-get install -y nodejs && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/* && \
-    npm install -g yarn
-
-COPY docs/requirements.txt /arrow/docs/
-RUN python3 -m venv ${ARROW_PYTHON_VENV} && \
-    . ${ARROW_PYTHON_VENV}/bin/activate && \
-    pip install -r arrow/docs/requirements.txt
-
 COPY c_glib/Gemfile /arrow/c_glib/
 RUN gem install --no-document bundler && \
     bundle install --gemfile /arrow/c_glib/Gemfile
@@ -98,6 +101,17 @@ COPY r/DESCRIPTION /arrow/r/
 RUN /arrow/ci/scripts/r_deps.sh /arrow && \
     R -e "install.packages('pkgdown')"
 
+RUN useradd --user-group --create-home arrow
+RUN echo "arrow ALL=(ALL:ALL) NOPASSWD:ALL" | \
+        EDITOR=tee visudo -f /etc/sudoers.d/arrow
+USER arrow
+
+COPY docs/requirements.txt /arrow/docs/
+RUN sudo chown -R arrow: ${ARROW_PYTHON_VENV} && \
+    python3 -m venv ${ARROW_PYTHON_VENV} && \
+    . ${ARROW_PYTHON_VENV}/bin/activate && \
+    pip install -r arrow/docs/requirements.txt
+
 ENV ARROW_ACERO=ON \
     ARROW_AZURE=OFF \
     ARROW_BUILD_STATIC=OFF \

ci/scripts/cpp_build.sh

@@ -229,12 +229,17 @@ find . -name "*.o" -delete
 popd
 
 if [ -x "$(command -v ldconfig)" ]; then
-  ldconfig ${ARROW_HOME}/${CMAKE_INSTALL_LIBDIR:-lib}
+  if [ -x "$(command -v sudo)" ]; then
+    SUDO=sudo
+  else
+    SUDO=
+  fi
+  ${SUDO} ldconfig ${ARROW_HOME}/${CMAKE_INSTALL_LIBDIR:-lib}
 fi
 
 if [ "${ARROW_USE_CCACHE}" == "ON" ]; then
-    echo -e "===\n=== ccache statistics after build\n==="
-    ccache -sv 2>/dev/null || ccache -s
+  echo -e "===\n=== ccache statistics after build\n==="
+  ccache -sv 2>/dev/null || ccache -s
 fi
 
 if command -v sccache &> /dev/null; then
@@ -244,6 +249,6 @@ fi
 
 if [ "${BUILD_DOCS_CPP}" == "ON" ]; then
   pushd ${source_dir}/apidoc
-  doxygen
+  OUTPUT_DIRECTORY=${build_dir}/apidoc doxygen
   popd
 fi

ci/scripts/java_build.sh

@@ -75,7 +75,12 @@ fi
 # Use `2 * ncores` threads
 mvn="${mvn} -T 2C"
 
-pushd ${source_dir}
+mkdir -p ${build_dir}
+rm -rf ${build_dir}/format
+cp -aL ${arrow_dir}/format ${build_dir}/
+rm -rf ${build_dir}/java
+cp -aL ${source_dir} ${build_dir}/
+pushd ${build_dir}/java
 
 if [ "${ARROW_JAVA_SHADE_FLATBUFFERS}" == "ON" ]; then
   mvn="${mvn} -Pshade-flatbuffers"
@@ -95,7 +100,7 @@ if [ "${BUILD_DOCS_JAVA}" == "ON" ]; then
   # HTTP pooling is turned of to avoid download issues https://issues.apache.org/jira/browse/ARROW-11633
   mkdir -p ${build_dir}/docs/java/reference
   ${mvn} -Dcheckstyle.skip=true -Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false clean install site
-  rsync -a ${arrow_dir}/java/target/site/apidocs/ ${build_dir}/docs/java/reference
+  rsync -a target/site/apidocs/ ${build_dir}/docs/java/reference
 fi
 
 popd

ci/scripts/js_build.sh

@@ -25,7 +25,12 @@ build_dir=${2}
 
 : ${BUILD_DOCS_JS:=OFF}
 
-pushd ${source_dir}
+rm -rf ${build_dir}/js
+mkdir -p ${build_dir}
+cp -aL ${arrow_dir}/LICENSE.txt ${build_dir}/
+cp -aL ${arrow_dir}/NOTICE.txt ${build_dir}/
+cp -aL ${source_dir} ${build_dir}/js
+pushd ${build_dir}/js
 
 yarn --immutable
 yarn lint:ci
@@ -34,18 +39,18 @@ yarn build
 if [ "${BUILD_DOCS_JS}" == "ON" ]; then
   # If apache or upstream are defined use those as remote.
   # Otherwise use origin which could be a fork on PRs.
-  if [ "$(git config --get remote.apache.url)" == "[email protected]:apache/arrow.git" ]; then
+  if [ "$(git -C ${arrow_dir} config --get remote.apache.url)" == "[email protected]:apache/arrow.git" ]; then
     yarn doc --gitRemote apache
-  elif [[ "$(git config --get remote.upstream.url)" =~ "https://github.com/apache/arrow" ]]; then
+  elif [[ "$(git -C ${arrow_dir}config --get remote.upstream.url)" =~ "https://github.com/apache/arrow" ]]; then
     yarn doc --gitRemote upstream
-  elif [[ "$(basename -s .git $(git config --get remote.origin.url))" == "arrow" ]]; then
+  elif [[ "$(basename -s .git $(git -C ${arrow_dir} config --get remote.origin.url))" == "arrow" ]]; then
     yarn doc
   else
     echo "Failed to build docs because the remote is not set correctly. Please set the origin or upstream remote to https://github.com/apache/arrow.git or the apache remote to [email protected]:apache/arrow.git."
     exit 0
   fi
   mkdir -p ${build_dir}/docs/js
-  rsync -a ${arrow_dir}/js/doc/ ${build_dir}/docs/js
+  rsync -a doc/ ${build_dir}/docs/js
 fi
 
 popd

ci/scripts/python_build.sh

@@ -78,17 +78,18 @@ export PYARROW_PARALLEL=${n_jobs}
 export CMAKE_PREFIX_PATH
 export LD_LIBRARY_PATH=${ARROW_HOME}/lib:${LD_LIBRARY_PATH}
 
-pushd ${source_dir}
+rm -rf ${python_build_dir}
+cp -aL ${source_dir} ${python_build_dir}
+pushd ${python_build_dir}
 # - Cannot call setup.py as it may install in the wrong directory
 #   on Debian/Ubuntu (ARROW-15243).
 # - Cannot use build isolation as we want to use specific dependency versions
 #   (e.g. Numpy, Pandas) on some CI jobs.
 ${PYTHON:-python} -m pip install --no-deps --no-build-isolation -vv .
-# Remove build artifacts from source directory
-find build/ -user root -delete
 popd
 
 if [ "${BUILD_DOCS_PYTHON}" == "ON" ]; then
   ncpus=$(python -c "import os; print(os.cpu_count())")
+  export ARROW_CPP_DOXYGEN_XML=${build_dir}/cpp/apidoc/xml
   sphinx-build -b html -j ${ncpus} ${arrow_dir}/docs/source ${build_dir}/docs
 fi

ci/scripts/r_build.sh

@@ -24,15 +24,25 @@ build_dir=${2}
 
 : ${BUILD_DOCS_R:=OFF}
 
-pushd ${source_dir}
+rm -rf ${build_dir}/r
+cp -aL ${source_dir} ${build_dir}/r
+pushd ${build_dir}/r
 
 # build first so that any stray compiled files in r/src are ignored
 ${R_BIN} CMD build .
-${R_BIN} CMD INSTALL ${INSTALL_ARGS} arrow*.tar.gz
+if [ -x "$(command -v sudo)" ]; then
+  SUDO=sudo
+else
+  SUDO=
+fi
+${SUDO} \
+  env \
+    PKG_CONFIG_PATH=${ARROW_HOME}/lib/pkgconfig:${PKG_CONFIG_PATH} \
+      ${R_BIN} CMD INSTALL ${INSTALL_ARGS} arrow*.tar.gz
 
 if [ "${BUILD_DOCS_R}" == "ON" ]; then
   ${R_BIN} -e "pkgdown::build_site(install = FALSE)"
-  rsync -a ${source_dir}/docs/ ${build_dir}/docs/r
+  rsync -a docs/ ${build_dir}/docs/r
 fi
 
 popd

dev/tasks/tasks.yml

@@ -1594,8 +1594,8 @@ tasks:
     template: docs/github.linux.yml
     params:
       env:
-        UBUNTU: 22.04
+        JDK: 17
       pr_number: Unset
       flags: "-v $PWD/build/:/build/"
-      image: ubuntu-docs
+      image: debian-docs
       publish: true

docker-compose.yml

@@ -131,7 +131,8 @@ x-hierarchy:
   - debian-cpp:
     - debian-c-glib:
       - debian-ruby
-    - debian-python
+    - debian-python:
+      - debian-docs
   - debian-go:
     - debian-go-cgo
     - debian-go-cgo-python
@@ -145,8 +146,7 @@ x-hierarchy:
     - ubuntu-c-glib:
       - ubuntu-ruby
     - ubuntu-lint
-    - ubuntu-python:
-      - ubuntu-docs
+    - ubuntu-python
     - ubuntu-python-sdist-test
     - ubuntu-r
     - ubuntu-r-only-r
@@ -1759,29 +1759,30 @@ services:
 
   ################################ Docs #######################################
 
-  ubuntu-docs:
+  debian-docs:
     # Usage:
-    #   docker-compose build ubuntu-cpp
-    #   docker-compose build ubuntu-python
-    #   docker-compose build ubuntu-docs
-    #   docker-compose run --rm ubuntu-docs
-    image: ${REPO}:${ARCH}-ubuntu-${UBUNTU}-docs
+    #   docker-compose build debian-cpp
+    #   docker-compose build debian-python
+    #   docker-compose build debian-docs
+    #   docker-compose run --rm debian-docs
+    image: ${REPO}:${ARCH}-debian-${DEBIAN}-docs
     build:
       context: .
       dockerfile: ci/docker/linux-apt-docs.dockerfile
       cache_from:
-        - ${REPO}:${ARCH}-ubuntu-${UBUNTU}-docs
+        - ${REPO}:${ARCH}-debian-${DEBIAN}-docs
       args:
         r: ${R}
         jdk: ${JDK}
         maven: ${MAVEN}
         node: ${NODE}
-        base: ${REPO}:${ARCH}-ubuntu-${UBUNTU}-python-3
+        base: ${REPO}:${ARCH}-debian-${DEBIAN}-python-3
     environment:
       <<: [*common, *ccache]
       ARROW_CUDA: "ON"
       ARROW_CXX_FLAGS_DEBUG: "-g1"
       ARROW_C_FLAGS_DEBUG: "-g1"
+      ARROW_HOME: "/tmp/local"
       ARROW_JAVA_SKIP_GIT_PLUGIN:
       ARROW_SUBSTRAIT: "ON"
       BUILD_DOCS_C_GLIB: "ON"
@@ -1790,9 +1791,11 @@ services:
       BUILD_DOCS_JS: "ON"
       BUILD_DOCS_PYTHON: "ON"
       BUILD_DOCS_R: "ON"
-    volumes: *ubuntu-volumes
-    command: &docs-command >
+    volumes: *debian-volumes
+    command: >
       /bin/bash -c "
+        sudo mkdir -p /build /ccache &&
+        sudo chown -R `id --user --name`: /build /ccache &&
         /arrow/ci/scripts/cpp_build.sh /arrow /build &&
         /arrow/ci/scripts/python_build.sh /arrow /build &&
         /arrow/ci/scripts/c_glib_build.sh /arrow /build &&

docs/requirements.txt

@@ -8,7 +8,8 @@ myst-parser[linkify]
 numpydoc
 pydata-sphinx-theme~=0.14
 sphinx-autobuild
-sphinx-design
 sphinx-copybutton
+sphinx-design
+sphinxcontrib-mermaid
 sphinx==6.2
 pandas