feat(docs): introduce C++ documentation

.gitignore

@@ -48,6 +48,7 @@ FlameGraph
 
 # Images
 *.svg
+!docs/source/_static/prefetch.svg
 
 # Third party dependencies archives
 third_party/*.tar.gz

docs/.gitignore

@@ -0,0 +1,18 @@
+# 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.
+
+_build

docs/Makefile

@@ -0,0 +1,46 @@
+# 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.
+
+# Adapted from Apache Arrow
+# https://github.com/apache/arrow/blob/main/docs/Makefile
+
+#
+# Makefile for Sphinx documentation
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    = -j8
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(SPHINXOPTS) source $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

docs/code-style.md

@@ -31,6 +31,21 @@ This document defines the coding conventions for the paimon-cpp project. All pul
 
 ---
 
+## Integer Types
+
+Use **fixed-width integer types** from `<cstdint>`. Do **not** use plain `int`, `long`, `short`, or `unsigned`.
+
+| Use | Instead of |
+|-----|-----------|
+| `int8_t` / `uint8_t` | `char` (for numeric data) |
+| `int16_t` / `uint16_t` | `short` |
+| `int32_t` / `uint32_t` | `int` / `unsigned int` |
+| `int64_t` / `uint64_t` | `long` / `long long` |
+
+**Exception**: Loop variables iterating over small, bounded ranges (e.g. `for (int32_t i = 0; i < n; ++i)`) must still use `int32_t`, not `int`.
+
+---
+
 ## Formatting
 
 Formatting is based on **Google C++ Style** with the following overrides (defined in `.clang-format`):

docs/make.bat

@@ -0,0 +1,55 @@
+@rem Licensed to the Apache Software Foundation (ASF) under one
+@rem or more contributor license agreements.  See the NOTICE file
+@rem distributed with this work for additional information
+@rem regarding copyright ownership.  The ASF licenses this file
+@rem to you under the Apache License, Version 2.0 (the
+@rem "License"); you may not use this file except in compliance
+@rem with the License.  You may obtain a copy of the License at
+@rem
+@rem   http://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing,
+@rem software distributed under the License is distributed on an
+@rem "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+@rem KIND, either express or implied.  See the License for the
+@rem specific language governing permissions and limitations
+@rem under the License.
+
+@rem Adapted from Apache Arrow
+@rem https://github.com/apache/arrow/blob/main/docs/make.bat
+
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,13 @@
+#
+# Note: keep this file in sync with conda_env_sphinx.txt !
+#
+
+breathe
+myst-parser[linkify]
+pydata-sphinx-theme~=0.16
+sphinx-autobuild
+sphinx-copybutton
+sphinx-design
+sphinx-lint
+sphinxcontrib-mermaid
+sphinx

docs/source/_static/theme_overrides.css

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+
+/* Adapted from Apache Arrow */
+/* https://github.com/apache/arrow/blob/main/docs/source/_static/theme_overrides.css */
+
+/* Customizing with theme CSS variables */
+
+:root {
+  /* Make headings more bold */
+  --pst-font-weight-heading: 600;
+}
+
+/* Contributing landing page overview cards */
+
+.contrib-card {
+  border-radius: 0;
+  padding: 30px 10px 20px 10px;
+  margin: 10px 0px;
+}
+
+.contrib-card p.card-text {
+  margin: 0px;
+}
+
+.contrib-card .sd-card-img-top {
+  margin: 2px;
+  height: 75px;
+  background: none !important;
+}
+
+.contrib-card .sd-card-title {
+  color: var(--pst-color-primary);
+  font-size: var(--pst-font-size-h3);
+  padding: 1rem 0rem 0.5rem 0rem;
+}
+
+.contrib-card .sd-card-footer {
+  border: none;
+}
+
+/* This is the bootstrap CSS style for "table-striped". Since the theme does
+not yet provide an easy way to configure this globally, it easier to simply
+include this snippet here than updating each table in all rst files to
+add ":class: table-striped" */
+
+.table tbody tr:nth-of-type(odd) {
+  background-color: rgba(0, 0, 0, 0.05);
+}
+
+/* Improve the vertical spacing in the C++ API docs
+(ideally this should be upstreamed to the pydata-sphinx-theme */
+
+dl.cpp dd p {
+  margin-bottom: .4rem;
+}
+
+dl.cpp.enumerator {
+  margin-bottom: 0.2rem;
+}
+
+p.breathe-sectiondef-title {
+  margin-top: 1rem;
+}
+
+/* Keep social icons arranged horizontally in sidebar */
+
+.sidebar-header-items__end {
+  flex-wrap: wrap;
+}

docs/source/_static/versions.json

@@ -0,0 +1,7 @@
+[
+    {
+        "name": "0.10.0 (dev)",
+        "version": "dev/",
+        "url": "#"
+    }
+]

docs/source/api.rst

@@ -0,0 +1,40 @@
+.. 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.
+
+*************
+API Reference
+*************
+
+.. toctree::
+   :maxdepth: 3
+
+   api/catalog
+   api/write
+   api/commit
+   api/scan
+   api/read
+   api/predicate
+   api/file_format
+   api/file_system
+   api/io
+   api/data_types
+   api/file_index
+   api/global_index
+   api/clean
+   api/defs
+   api/executor
+   api/memory

docs/source/api/catalog.rst

@@ -0,0 +1,32 @@
+.. 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.
+
+===========
+Catalog
+===========
+
+.. _cpp-api-catalog:
+
+Interface
+=========
+
+.. doxygenclass:: paimon::Catalog
+   :members:
+
+.. doxygenclass:: paimon::Identifier
+   :members:
+   :undoc-members:

docs/source/api/clean.rst

@@ -0,0 +1,37 @@
+.. 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.
+
+==================
+Orphan Files Clean
+==================
+
+.. _cpp-api-clean:
+
+Interface
+=========
+
+.. doxygenclass:: paimon::OrphanFilesCleaner
+   :members:
+   :undoc-members:
+
+.. doxygenclass:: paimon::CleanContextBuilder
+   :members:
+   :undoc-members:
+
+.. doxygenclass:: paimon::CleanContext
+   :members:
+   :undoc-members: