From 1b56409396899ff5b079ebe1189af612686e3255 Mon Sep 17 00:00:00 2001 From: David Li Date: Mon, 30 Oct 2023 10:31:44 -0400 Subject: [PATCH] docs: pre-render Mermaid diagrams (#1234) Fixes #1217. --- CONTRIBUTING.md | 10 ++++ ci/conda_env_docs.txt | 1 - docs/mermaid.makefile | 57 +++++++++++++++++++ docs/source/conf.py | 7 --- .../format/AdbcStatementBasicUsage.mmd.svg | 19 +++++++ .../format/AdbcStatementBulkIngest.mmd.svg | 19 +++++++ .../AdbcStatementConsumeResultSet.mmd.svg | 19 +++++++ .../format/AdbcStatementPartitioned.mmd.svg | 19 +++++++ .../source/format/AdbcStatementUpdate.mmd.svg | 19 +++++++ docs/source/format/specification.rst | 29 ++++++---- 10 files changed, 179 insertions(+), 20 deletions(-) create mode 100644 docs/mermaid.makefile create mode 100644 docs/source/format/AdbcStatementBasicUsage.mmd.svg create mode 100644 docs/source/format/AdbcStatementBulkIngest.mmd.svg create mode 100644 docs/source/format/AdbcStatementConsumeResultSet.mmd.svg create mode 100644 docs/source/format/AdbcStatementPartitioned.mmd.svg create mode 100644 docs/source/format/AdbcStatementUpdate.mmd.svg diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d8b2fe3198..8981fef402 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/ci/conda_env_docs.txt b/ci/conda_env_docs.txt index 527f488264..ff2b6df33f 100644 --- a/ci/conda_env_docs.txt +++ b/ci/conda_env_docs.txt @@ -28,5 +28,4 @@ sphinx>=5.0 sphinx-autobuild sphinx-copybutton sphinx-design -sphinxcontrib-mermaid r-pkgdown diff --git a/docs/mermaid.makefile b/docs/mermaid.makefile new file mode 100644 index 0000000000..9b46cf35e1 --- /dev/null +++ b/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 $@ $@.tmp + echo "" >> $@ + cat $@.tmp >> $@ + echo "" >> $@ + rm -f $@.tmp + +.PHONY: all + +all : $(DIAGRAMS) diff --git a/docs/source/conf.py b/docs/source/conf.py index 9f7a4181aa..f0c0b9c61b 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/format/AdbcStatementBasicUsage.mmd.svg b/docs/source/format/AdbcStatementBasicUsage.mmd.svg new file mode 100644 index 0000000000..601f350206 --- /dev/null +++ b/docs/source/format/AdbcStatementBasicUsage.mmd.svg @@ -0,0 +1,19 @@ + +AdbcStatementAdbcStatementloop[As many times as desired]SetSqlQuery and repeat (if desired)AppNewSetSqlQueryPrepareGetParameterSchemaBindExecuteQueryArrowArrayStreamconsume result setReleaseApp diff --git a/docs/source/format/AdbcStatementBulkIngest.mmd.svg b/docs/source/format/AdbcStatementBulkIngest.mmd.svg new file mode 100644 index 0000000000..de3591c1ac --- /dev/null +++ b/docs/source/format/AdbcStatementBulkIngest.mmd.svg @@ -0,0 +1,19 @@ + +AdbcStatementAdbcStatementAppNewSetOption(ADBC_INGEST_OPTION_TARGET_TABLE)GetParameterSchemaBindExecuteUpdateReleaseApp diff --git a/docs/source/format/AdbcStatementConsumeResultSet.mmd.svg b/docs/source/format/AdbcStatementConsumeResultSet.mmd.svg new file mode 100644 index 0000000000..96e15a761c --- /dev/null +++ b/docs/source/format/AdbcStatementConsumeResultSet.mmd.svg @@ -0,0 +1,19 @@ + +ArrowArrayStreamArrowArrayStreamloop[Until streamexhausted]Appget_schemaArrowSchemaget_nextArrowArrayreleaseApp diff --git a/docs/source/format/AdbcStatementPartitioned.mmd.svg b/docs/source/format/AdbcStatementPartitioned.mmd.svg new file mode 100644 index 0000000000..235123fe8d --- /dev/null +++ b/docs/source/format/AdbcStatementPartitioned.mmd.svg @@ -0,0 +1,19 @@ + +Server 2Server 1AdbcStatementServer 2Server 1AdbcStatementConsume the distributed result setpar[Read from server 1][Read from server 2]loop[As many times as desired]SetSqlQuery and repeat (if desired)AppNewSetSqlQueryPrepareGetParameterSchemaBindExecutePartitionsAdbcPartitionsReadPartitionArrowArrayStreamconsume result setReadPartitionArrowArrayStreamconsume result setReleaseApp diff --git a/docs/source/format/AdbcStatementUpdate.mmd.svg b/docs/source/format/AdbcStatementUpdate.mmd.svg new file mode 100644 index 0000000000..b5db840949 --- /dev/null +++ b/docs/source/format/AdbcStatementUpdate.mmd.svg @@ -0,0 +1,19 @@ + +AdbcStatementAdbcStatementloop[As many times asdesired]SetSqlQuery and repeat (if desired)AppNewSetSqlQueryPrepareGetParameterSchemaBindExecuteUpdateaffected rowsReleaseApp diff --git a/docs/source/format/specification.rst b/docs/source/format/specification.rst index 89fc3597a0..19b73010cb 100644 --- a/docs/source/format/specification.rst +++ b/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" `. +.. figure:: AdbcStatementPartitioned.mmd.svg + + This is similar to fetching data in Arrow Flight RPC (by design). See + :doc:`"Downloading Data" `. Error Handling ==============