From 2353f0792d3baffe4d56dfb85aea31198ecb2900 Mon Sep 17 00:00:00 2001
From: "yonghao.fyh" <yonghao.fyh@alibaba-inc.com>
Date: Tue, 16 Dec 2025 09:09:38 +0000
Subject: [PATCH 1/2] fix: fix publish docs workflow

---
 .github/workflows/build_docs.yaml              | 2 +-
 docs/source/implementations/basic_concepts.rst | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/build_docs.yaml b/.github/workflows/build_docs.yaml
index 85afc979c..a02eccda6 100644
--- a/.github/workflows/build_docs.yaml
+++ b/.github/workflows/build_docs.yaml
@@ -48,7 +48,7 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y doxygen
-          make install-deps
+          pip install -r docs/requirements.txt
 
       - name: Build API
         run: |
diff --git a/docs/source/implementations/basic_concepts.rst b/docs/source/implementations/basic_concepts.rst
index 87d1c60a0..678e0042e 100644
--- a/docs/source/implementations/basic_concepts.rst
+++ b/docs/source/implementations/basic_concepts.rst
@@ -19,10 +19,10 @@
 .. https://github.com/apache/paimon/blob/master/docs/content/concepts/basic-concepts.md
 
 Basic Concepts
-=========================
+========================
 
 File Layouts
--------------------------
+------------------------
 All files of a table are stored under one base directory. Paimon files are
 organized in a layered style. The following image illustrates the file layout.
 Starting from a snapshot file, Paimon readers can recursively access all records

From d52fb3e23ac78d34c164aaee3978b0ae5698f9fb Mon Sep 17 00:00:00 2001
From: "yonghao.fyh" <yonghao.fyh@alibaba-inc.com>
Date: Tue, 16 Dec 2025 10:34:26 +0000
Subject: [PATCH 2/2] fix

---
 .github/workflows/build_docs.yaml             |   1 +
 docs/source/{implementations => }/api.rst     |   0
 .../{implementations => }/api/catalog.rst     |   0
 .../{implementations => }/api/clean.rst       |   0
 .../{implementations => }/api/commit.rst      |   0
 .../{implementations => }/api/data_types.rst  |   0
 .../source/{implementations => }/api/defs.rst |   0
 .../{implementations => }/api/executor.rst    |   0
 .../{implementations => }/api/file_format.rst |   0
 .../{implementations => }/api/file_index.rst  |   0
 .../{implementations => }/api/file_system.rst |   0
 .../api/global_index.rst                      |   0
 docs/source/{implementations => }/api/io.rst  |   0
 .../{implementations => }/api/memory.rst      |   0
 .../{implementations => }/api/predicate.rst   |   0
 .../source/{implementations => }/api/read.rst |   0
 .../source/{implementations => }/api/scan.rst |   0
 .../{implementations => }/api/write.rst       |   0
 .../{implementations => }/basic_concepts.rst  |   2 +-
 .../{implementations => }/build_system.rst    |   0
 .../source/{implementations => }/building.rst |   0
 docs/source/conf.py                           |   2 +-
 .../{implementations => }/documentations.rst  |   0
 .../{implementations => }/examples/clean.rst  |   0
 .../{implementations => }/examples/index.rst  |   0
 .../examples/write_commit_scan_read.rst       |   0
 .../{implementations => }/getting_started.rst |   4 +-
 docs/source/implementations/index.rst         | 105 ------------------
 docs/source/index.rst                         |  89 ++++++++++++++-
 .../{implementations => }/user_guide.rst      |   0
 .../user_guide/append_only_table.rst          |   0
 .../user_guide/arrow.rst                      |   0
 .../user_guide/catalog.rst                    |   0
 .../user_guide/clean.rst                      |   0
 .../user_guide/commit.rst                     |   0
 .../user_guide/data_types.rst                 |   0
 .../user_guide/manifest.rst                   |   0
 .../user_guide/prefetch.rst                   |   2 +-
 .../user_guide/primary_key_table.rst          |   2 +-
 .../{implementations => }/user_guide/read.rst |   0
 .../user_guide/schema.rst                     |   0
 .../user_guide/snapshot.rst                   |   0
 .../user_guide/write.rst                      |   0
 43 files changed, 92 insertions(+), 115 deletions(-)
 rename docs/source/{implementations => }/api.rst (100%)
 rename docs/source/{implementations => }/api/catalog.rst (100%)
 rename docs/source/{implementations => }/api/clean.rst (100%)
 rename docs/source/{implementations => }/api/commit.rst (100%)
 rename docs/source/{implementations => }/api/data_types.rst (100%)
 rename docs/source/{implementations => }/api/defs.rst (100%)
 rename docs/source/{implementations => }/api/executor.rst (100%)
 rename docs/source/{implementations => }/api/file_format.rst (100%)
 rename docs/source/{implementations => }/api/file_index.rst (100%)
 rename docs/source/{implementations => }/api/file_system.rst (100%)
 rename docs/source/{implementations => }/api/global_index.rst (100%)
 rename docs/source/{implementations => }/api/io.rst (100%)
 rename docs/source/{implementations => }/api/memory.rst (100%)
 rename docs/source/{implementations => }/api/predicate.rst (100%)
 rename docs/source/{implementations => }/api/read.rst (100%)
 rename docs/source/{implementations => }/api/scan.rst (100%)
 rename docs/source/{implementations => }/api/write.rst (100%)
 rename docs/source/{implementations => }/basic_concepts.rst (98%)
 rename docs/source/{implementations => }/build_system.rst (100%)
 rename docs/source/{implementations => }/building.rst (100%)
 rename docs/source/{implementations => }/documentations.rst (100%)
 rename docs/source/{implementations => }/examples/clean.rst (100%)
 rename docs/source/{implementations => }/examples/index.rst (100%)
 rename docs/source/{implementations => }/examples/write_commit_scan_read.rst (100%)
 rename docs/source/{implementations => }/getting_started.rst (87%)
 delete mode 100644 docs/source/implementations/index.rst
 rename docs/source/{implementations => }/user_guide.rst (100%)
 rename docs/source/{implementations => }/user_guide/append_only_table.rst (100%)
 rename docs/source/{implementations => }/user_guide/arrow.rst (100%)
 rename docs/source/{implementations => }/user_guide/catalog.rst (100%)
 rename docs/source/{implementations => }/user_guide/clean.rst (100%)
 rename docs/source/{implementations => }/user_guide/commit.rst (100%)
 rename docs/source/{implementations => }/user_guide/data_types.rst (100%)
 rename docs/source/{implementations => }/user_guide/manifest.rst (100%)
 rename docs/source/{implementations => }/user_guide/prefetch.rst (98%)
 rename docs/source/{implementations => }/user_guide/primary_key_table.rst (98%)
 rename docs/source/{implementations => }/user_guide/read.rst (100%)
 rename docs/source/{implementations => }/user_guide/schema.rst (100%)
 rename docs/source/{implementations => }/user_guide/snapshot.rst (100%)
 rename docs/source/{implementations => }/user_guide/write.rst (100%)

diff --git a/.github/workflows/build_docs.yaml b/.github/workflows/build_docs.yaml
index a02eccda6..872a51890 100644
--- a/.github/workflows/build_docs.yaml
+++ b/.github/workflows/build_docs.yaml
@@ -63,6 +63,7 @@ jobs:
             mkdir -p /tmp/site
             cp -r ./_build/html/* /tmp/site/
             cd -
+            touch .nojekyll
 
       - name: Deploy to gh-pages
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
diff --git a/docs/source/implementations/api.rst b/docs/source/api.rst
similarity index 100%
rename from docs/source/implementations/api.rst
rename to docs/source/api.rst
diff --git a/docs/source/implementations/api/catalog.rst b/docs/source/api/catalog.rst
similarity index 100%
rename from docs/source/implementations/api/catalog.rst
rename to docs/source/api/catalog.rst
diff --git a/docs/source/implementations/api/clean.rst b/docs/source/api/clean.rst
similarity index 100%
rename from docs/source/implementations/api/clean.rst
rename to docs/source/api/clean.rst
diff --git a/docs/source/implementations/api/commit.rst b/docs/source/api/commit.rst
similarity index 100%
rename from docs/source/implementations/api/commit.rst
rename to docs/source/api/commit.rst
diff --git a/docs/source/implementations/api/data_types.rst b/docs/source/api/data_types.rst
similarity index 100%
rename from docs/source/implementations/api/data_types.rst
rename to docs/source/api/data_types.rst
diff --git a/docs/source/implementations/api/defs.rst b/docs/source/api/defs.rst
similarity index 100%
rename from docs/source/implementations/api/defs.rst
rename to docs/source/api/defs.rst
diff --git a/docs/source/implementations/api/executor.rst b/docs/source/api/executor.rst
similarity index 100%
rename from docs/source/implementations/api/executor.rst
rename to docs/source/api/executor.rst
diff --git a/docs/source/implementations/api/file_format.rst b/docs/source/api/file_format.rst
similarity index 100%
rename from docs/source/implementations/api/file_format.rst
rename to docs/source/api/file_format.rst
diff --git a/docs/source/implementations/api/file_index.rst b/docs/source/api/file_index.rst
similarity index 100%
rename from docs/source/implementations/api/file_index.rst
rename to docs/source/api/file_index.rst
diff --git a/docs/source/implementations/api/file_system.rst b/docs/source/api/file_system.rst
similarity index 100%
rename from docs/source/implementations/api/file_system.rst
rename to docs/source/api/file_system.rst
diff --git a/docs/source/implementations/api/global_index.rst b/docs/source/api/global_index.rst
similarity index 100%
rename from docs/source/implementations/api/global_index.rst
rename to docs/source/api/global_index.rst
diff --git a/docs/source/implementations/api/io.rst b/docs/source/api/io.rst
similarity index 100%
rename from docs/source/implementations/api/io.rst
rename to docs/source/api/io.rst
diff --git a/docs/source/implementations/api/memory.rst b/docs/source/api/memory.rst
similarity index 100%
rename from docs/source/implementations/api/memory.rst
rename to docs/source/api/memory.rst
diff --git a/docs/source/implementations/api/predicate.rst b/docs/source/api/predicate.rst
similarity index 100%
rename from docs/source/implementations/api/predicate.rst
rename to docs/source/api/predicate.rst
diff --git a/docs/source/implementations/api/read.rst b/docs/source/api/read.rst
similarity index 100%
rename from docs/source/implementations/api/read.rst
rename to docs/source/api/read.rst
diff --git a/docs/source/implementations/api/scan.rst b/docs/source/api/scan.rst
similarity index 100%
rename from docs/source/implementations/api/scan.rst
rename to docs/source/api/scan.rst
diff --git a/docs/source/implementations/api/write.rst b/docs/source/api/write.rst
similarity index 100%
rename from docs/source/implementations/api/write.rst
rename to docs/source/api/write.rst
diff --git a/docs/source/implementations/basic_concepts.rst b/docs/source/basic_concepts.rst
similarity index 98%
rename from docs/source/implementations/basic_concepts.rst
rename to docs/source/basic_concepts.rst
index 678e0042e..10143e909 100644
--- a/docs/source/implementations/basic_concepts.rst
+++ b/docs/source/basic_concepts.rst
@@ -28,7 +28,7 @@ organized in a layered style. The following image illustrates the file layout.
 Starting from a snapshot file, Paimon readers can recursively access all records
 from the table.
 
-.. image:: ../_static/file-layout.png
+.. image:: _static/file-layout.png
    :alt: File Layout
    :align: center
    :width: 100%
diff --git a/docs/source/implementations/build_system.rst b/docs/source/build_system.rst
similarity index 100%
rename from docs/source/implementations/build_system.rst
rename to docs/source/build_system.rst
diff --git a/docs/source/implementations/building.rst b/docs/source/building.rst
similarity index 100%
rename from docs/source/implementations/building.rst
rename to docs/source/building.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 6dee489dc..cb6ac8531 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -111,7 +111,7 @@
 }
 
 # The master toctree document.
-master_doc = "implementations/index"
+master_doc = "index"
 
 version = "0.9.0"
 
diff --git a/docs/source/implementations/documentations.rst b/docs/source/documentations.rst
similarity index 100%
rename from docs/source/implementations/documentations.rst
rename to docs/source/documentations.rst
diff --git a/docs/source/implementations/examples/clean.rst b/docs/source/examples/clean.rst
similarity index 100%
rename from docs/source/implementations/examples/clean.rst
rename to docs/source/examples/clean.rst
diff --git a/docs/source/implementations/examples/index.rst b/docs/source/examples/index.rst
similarity index 100%
rename from docs/source/implementations/examples/index.rst
rename to docs/source/examples/index.rst
diff --git a/docs/source/implementations/examples/write_commit_scan_read.rst b/docs/source/examples/write_commit_scan_read.rst
similarity index 100%
rename from docs/source/implementations/examples/write_commit_scan_read.rst
rename to docs/source/examples/write_commit_scan_read.rst
diff --git a/docs/source/implementations/getting_started.rst b/docs/source/getting_started.rst
similarity index 87%
rename from docs/source/implementations/getting_started.rst
rename to docs/source/getting_started.rst
index 3aad873d6..643f3316c 100644
--- a/docs/source/implementations/getting_started.rst
+++ b/docs/source/getting_started.rst
@@ -23,8 +23,8 @@ understanding of C++ Paimon. These articles will get you set up quickly with C++
 Paimon and give you a taste of what the library is capable of.
 
 Start here to gain a basic understanding of Paimon, and move on to the
-:doc:`/implementations/user_guide` to explore more specific topics and
-underlying concepts, or the :doc:`/implementations/api` to explore Paimon's API.
+:doc:`/user_guide` to explore more specific topics and
+underlying concepts, or the :doc:`/api` to explore Paimon's API.
 
 .. toctree::
 
diff --git a/docs/source/implementations/index.rst b/docs/source/implementations/index.rst
deleted file mode 100644
index 1779c83a9..000000000
--- a/docs/source/implementations/index.rst
+++ /dev/null
@@ -1,105 +0,0 @@
-.. Copyright 2024-present Alibaba Inc.
-
-.. Licensed 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.
-
-.. _implementations:
-
-C++ Paimon Documentation
-========================
-
-Paimon C++ is a high-performance C++ implementation of Apache Paimon. We aim to
-provide a native, high-performance and extensible implementation that allows
-native engines to access the Paimon datalake format with maximum efficiency.
-
-.. grid:: 1 2 2 2
-   :gutter: 4
-   :padding: 2 2 0 0
-   :class-container: sd-text-center
-
-   .. grid-item-card:: Getting started
-      :class-card: contrib-card
-      :shadow: none
-
-      Start here to gain a basic understanding of Paimon with
-      an installation and linking guide, basic concepts etc.
-
-      +++
-
-      .. button-link:: getting_started.html
-         :click-parent:
-         :color: primary
-         :expand:
-
-         To Getting started
-
-   .. grid-item-card:: User Guide
-      :class-card: contrib-card
-      :shadow: none
-
-      Explore more specific topics and underlying concepts
-      of Paimon C++
-
-      +++
-
-      .. button-link:: user_guide.html
-         :click-parent:
-         :color: primary
-         :expand:
-
-         To the User Guide
-
-.. grid:: 1 2 2 2
-   :gutter: 4
-   :padding: 2 2 0 0
-   :class-container: sd-text-center
-
-   .. grid-item-card:: Examples
-      :class-card: contrib-card
-      :shadow: none
-
-      Find the description and location of the examples
-      using Paimon C++ library
-
-      +++
-
-      .. button-link:: examples/index.html
-         :click-parent:
-         :color: primary
-         :expand:
-
-         To the Examples
-
-   .. grid-item-card:: API Reference
-      :class-card: contrib-card
-      :shadow: none
-
-      Explore Paimon‘s API reference documentation
-
-      +++
-
-      .. button-link:: api.html
-         :click-parent:
-         :color: primary
-         :expand:
-
-         To the API Reference
-
-
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-
-   getting_started
-   user_guide
-   Examples <examples/index>
-   api
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 018b7d332..1779c83a9 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -12,13 +12,94 @@
 .. See the License for the specific language governing permissions and
 .. limitations under the License.
 
-:html_theme.sidebar_secondary.remove:
+.. _implementations:
+
+C++ Paimon Documentation
+========================
+
+Paimon C++ is a high-performance C++ implementation of Apache Paimon. We aim to
+provide a native, high-performance and extensible implementation that allows
+native engines to access the Paimon datalake format with maximum efficiency.
+
+.. grid:: 1 2 2 2
+   :gutter: 4
+   :padding: 2 2 0 0
+   :class-container: sd-text-center
+
+   .. grid-item-card:: Getting started
+      :class-card: contrib-card
+      :shadow: none
+
+      Start here to gain a basic understanding of Paimon with
+      an installation and linking guide, basic concepts etc.
+
+      +++
+
+      .. button-link:: getting_started.html
+         :click-parent:
+         :color: primary
+         :expand:
+
+         To Getting started
+
+   .. grid-item-card:: User Guide
+      :class-card: contrib-card
+      :shadow: none
+
+      Explore more specific topics and underlying concepts
+      of Paimon C++
+
+      +++
+
+      .. button-link:: user_guide.html
+         :click-parent:
+         :color: primary
+         :expand:
+
+         To the User Guide
+
+.. grid:: 1 2 2 2
+   :gutter: 4
+   :padding: 2 2 0 0
+   :class-container: sd-text-center
+
+   .. grid-item-card:: Examples
+      :class-card: contrib-card
+      :shadow: none
+
+      Find the description and location of the examples
+      using Paimon C++ library
+
+      +++
+
+      .. button-link:: examples/index.html
+         :click-parent:
+         :color: primary
+         :expand:
+
+         To the Examples
+
+   .. grid-item-card:: API Reference
+      :class-card: contrib-card
+      :shadow: none
+
+      Explore Paimon‘s API reference documentation
+
+      +++
+
+      .. button-link:: api.html
+         :click-parent:
+         :color: primary
+         :expand:
+
+         To the API Reference
 
-C++ Paimon
-============
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
-   implementations/index
+   getting_started
+   user_guide
+   Examples <examples/index>
+   api
diff --git a/docs/source/implementations/user_guide.rst b/docs/source/user_guide.rst
similarity index 100%
rename from docs/source/implementations/user_guide.rst
rename to docs/source/user_guide.rst
diff --git a/docs/source/implementations/user_guide/append_only_table.rst b/docs/source/user_guide/append_only_table.rst
similarity index 100%
rename from docs/source/implementations/user_guide/append_only_table.rst
rename to docs/source/user_guide/append_only_table.rst
diff --git a/docs/source/implementations/user_guide/arrow.rst b/docs/source/user_guide/arrow.rst
similarity index 100%
rename from docs/source/implementations/user_guide/arrow.rst
rename to docs/source/user_guide/arrow.rst
diff --git a/docs/source/implementations/user_guide/catalog.rst b/docs/source/user_guide/catalog.rst
similarity index 100%
rename from docs/source/implementations/user_guide/catalog.rst
rename to docs/source/user_guide/catalog.rst
diff --git a/docs/source/implementations/user_guide/clean.rst b/docs/source/user_guide/clean.rst
similarity index 100%
rename from docs/source/implementations/user_guide/clean.rst
rename to docs/source/user_guide/clean.rst
diff --git a/docs/source/implementations/user_guide/commit.rst b/docs/source/user_guide/commit.rst
similarity index 100%
rename from docs/source/implementations/user_guide/commit.rst
rename to docs/source/user_guide/commit.rst
diff --git a/docs/source/implementations/user_guide/data_types.rst b/docs/source/user_guide/data_types.rst
similarity index 100%
rename from docs/source/implementations/user_guide/data_types.rst
rename to docs/source/user_guide/data_types.rst
diff --git a/docs/source/implementations/user_guide/manifest.rst b/docs/source/user_guide/manifest.rst
similarity index 100%
rename from docs/source/implementations/user_guide/manifest.rst
rename to docs/source/user_guide/manifest.rst
diff --git a/docs/source/implementations/user_guide/prefetch.rst b/docs/source/user_guide/prefetch.rst
similarity index 98%
rename from docs/source/implementations/user_guide/prefetch.rst
rename to docs/source/user_guide/prefetch.rst
index 7648e3ead..bbd3c4df2 100644
--- a/docs/source/implementations/user_guide/prefetch.rst
+++ b/docs/source/user_guide/prefetch.rst
@@ -15,7 +15,7 @@
 Prefetch
 ========
 
-.. image:: ../../_static/prefetch.svg
+.. image:: ../_static/prefetch.svg
    :alt: File Layout
    :align: center
    :width: 100%
diff --git a/docs/source/implementations/user_guide/primary_key_table.rst b/docs/source/user_guide/primary_key_table.rst
similarity index 98%
rename from docs/source/implementations/user_guide/primary_key_table.rst
rename to docs/source/user_guide/primary_key_table.rst
index 42cca2bab..7a7e25a38 100644
--- a/docs/source/implementations/user_guide/primary_key_table.rst
+++ b/docs/source/user_guide/primary_key_table.rst
@@ -67,7 +67,7 @@ or multiple data files and each data file belongs to exactly one sorted run.
 Records within a data file are sorted by their primary keys. Within a sorted run,
 ranges of primary keys of data files never overlap.
 
-.. image:: ../../_static/sorted-runs.png
+.. image:: ../_static/sorted-runs.png
    :alt: Sorted Runs
    :align: center
    :width: 100%
diff --git a/docs/source/implementations/user_guide/read.rst b/docs/source/user_guide/read.rst
similarity index 100%
rename from docs/source/implementations/user_guide/read.rst
rename to docs/source/user_guide/read.rst
diff --git a/docs/source/implementations/user_guide/schema.rst b/docs/source/user_guide/schema.rst
similarity index 100%
rename from docs/source/implementations/user_guide/schema.rst
rename to docs/source/user_guide/schema.rst
diff --git a/docs/source/implementations/user_guide/snapshot.rst b/docs/source/user_guide/snapshot.rst
similarity index 100%
rename from docs/source/implementations/user_guide/snapshot.rst
rename to docs/source/user_guide/snapshot.rst
diff --git a/docs/source/implementations/user_guide/write.rst b/docs/source/user_guide/write.rst
similarity index 100%
rename from docs/source/implementations/user_guide/write.rst
rename to docs/source/user_guide/write.rst