docs: pre-render Mermaid diagrams (#1234)

Fixes #1217.

CONTRIBUTING.md

@@ -160,6 +160,16 @@ $ make html
 
 The output can be found in `build/`.
 
+Some documentations are maintained as [Mermaid][mermaid] diagrams, which must
+be rendered and checked in.  This can be done as follows:
+
+```shell
+cd docs
+make -f mermaid.makefile -j all
+# Check in the updated files
+```
+
+[mermaid]: https://mermaid.js.org/
 [sphinx]: https://www.sphinx-doc.org/en/master/
 
 ### GLib

ci/conda_env_docs.txt

@@ -28,5 +28,4 @@ sphinx>=5.0
 sphinx-autobuild
 sphinx-copybutton
 sphinx-design
-sphinxcontrib-mermaid
 r-pkgdown

docs/mermaid.makefile

@@ -0,0 +1,57 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Generate Mermaid diagrams statically.  Sphinx has a mermaid
+# extension, but this causes issues with the page shifting during
+# load.
+# Use as: make -f mermaid.makefile -j all
+
+MERMAID := $(shell find source/ -type f -name '*.mmd')
+DIAGRAMS := $(patsubst %.mmd,%.mmd.svg,$(MERMAID))
+
+define LICENSE
+endef
+
+%.mmd.svg : %.mmd
+	mmdc --input $< --output $@
+# Prepend the license header
+	mv $@ [email protected]
+	echo "<!--" >> $@
+	echo "  Licensed to the Apache Software Foundation (ASF) under one" >> $@
+	echo "  or more contributor license agreements.  See the NOTICE file" >> $@
+	echo "  distributed with this work for additional information" >> $@
+	echo "  regarding copyright ownership.  The ASF licenses this file" >> $@
+	echo "  to you under the Apache License, Version 2.0 (the" >> $@
+	echo "  \"License\"); you may not use this file except in compliance" >> $@
+	echo "  with the License.  You may obtain a copy of the License at" >> $@
+	echo "" >> $@
+	echo "    http://www.apache.org/licenses/LICENSE-2.0" >> $@
+	echo "" >> $@
+	echo "  Unless required by applicable law or agreed to in writing," >> $@
+	echo "  software distributed under the License is distributed on an" >> $@
+	echo "  \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY" >> $@
+	echo "  KIND, either express or implied.  See the License for the" >> $@
+	echo "  specific language governing permissions and limitations" >> $@
+	echo "  under the License." >> $@
+	echo "-->" >> $@
+	cat [email protected] >> $@
+	echo "" >> $@
+	rm -f [email protected]
+
+.PHONY: all
+
+all : $(DIAGRAMS)

docs/source/conf.py

@@ -43,7 +43,6 @@
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "sphinx_design",
-    "sphinxcontrib.mermaid",
 ]
 templates_path = ["_templates"]
 
@@ -108,12 +107,6 @@
     "arrow": ("https://arrow.apache.org/docs/", None),
 }
 
-# -- Options for mermaid -----------------------------------------------------
-
-mermaid_d3_zoom = False
-# Prerender images to avoid page jumping on load
-mermaid_output_format = "png"
-
 # -- Options for numpydoc ----------------------------------------------------
 
 numpydoc_class_members_toctree = False

docs/source/format/specification.rst

@@ -147,34 +147,39 @@ Lifecycle & Usage
 Basic Usage
 ~~~~~~~~~~~
 
-.. mermaid:: AdbcStatementBasicUsage.mmd
-   :caption: Preparing the statement and binding parameters are optional.
+.. figure:: AdbcStatementBasicUsage.mmd.svg
+
+   Preparing the statement and binding parameters are optional.
 
 Consuming Result Sets
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. mermaid:: AdbcStatementConsumeResultSet.mmd
-   :caption: This is equivalent to reading from what many Arrow
-             libraries call a RecordBatchReader.
+.. figure:: AdbcStatementConsumeResultSet.mmd.svg
+
+   This is equivalent to reading from what many Arrow libraries call a
+   RecordBatchReader.
 
 Bulk Data Ingestion
 ~~~~~~~~~~~~~~~~~~~
 
-.. mermaid:: AdbcStatementBulkIngest.mmd
-   :caption: There is no need to prepare the statement.
+.. figure:: AdbcStatementBulkIngest.mmd.svg
+
+   There is no need to prepare the statement.
 
 Update-only Queries (No Result Set)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. mermaid:: AdbcStatementUpdate.mmd
-   :caption: Preparing the statement and binding parameters are optional.
+.. figure:: AdbcStatementUpdate.mmd.svg
+
+   Preparing the statement and binding parameters are optional.
 
 Partitioned Execution
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. mermaid:: AdbcStatementPartitioned.mmd
-   :caption: This is similar to fetching data in Arrow Flight RPC (by
-             design). See :doc:`"Downloading Data" <arrow:format/Flight>`.
+.. figure:: AdbcStatementPartitioned.mmd.svg
+
+   This is similar to fetching data in Arrow Flight RPC (by design). See
+   :doc:`"Downloading Data" <arrow:format/Flight>`.
 
 Error Handling
 ==============