Docs: integrate PXF documentation as multi-instance plugin

.github/workflows/publish-cloudberry-site.yml

@@ -49,13 +49,31 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'
       - uses: actions/setup-node@v4
         with:
           node-version: 20
 
       # Install dependencies and build site
       - name: Install dependencies
         run: npm install
+
+      - name: Initialize submodules
+        run: |
+          echo "Initializing git submodules..."
+          git submodule update --init --recursive
+          echo "Submodules initialized"
+
+          # Configure sparse checkout for PXF submodule
+          if [ -f "scripts/setup-pxf-submodule.sh" ]; then
+            echo "Configuring sparse checkout for PXF submodule..."
+            chmod +x scripts/setup-pxf-submodule.sh
+            ./scripts/setup-pxf-submodule.sh
+            echo "Sparse checkout configured"
+          else
+            echo "WARNING: setup-pxf-submodule.sh not found, continuing without sparse checkout configuration"
+          fi
 
       - name: Build site
         run: |

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "pxf"]
+	path = pxf
+	url = https://github.com/apache/cloudberry-pxf.git
+	sparse-checkout = docs/

README.md

@@ -73,7 +73,18 @@ sure no errors when building.
 $ npm install
 ```
 
-3. Build and run
+3. Initialize submodules (required for PXF documentation)
+
+This repository uses git submodules to include PXF documentation. After cloning, run:
+
+```
+$ git submodule update --init --recursive
+$ ./scripts/setup-pxf-submodule.sh
+```
+
+The setup script configures sparse checkout to only include the `docs/` directory from the PXF submodule.
+
+4. Build and run
 
 ```
 $ npm run build

docs/sys-admin/expand-cluster/post-expansion-tasks.md

@@ -28,22 +28,15 @@ You can safely remove the expansion schema after the expansion operation is comp
 
 ## Set up PXF on the new host
 
+:::tip
+You can visit [PXF](/pxf) guides for more details.
+:::
+
 If you are using PXF in your Apache Cloudberry cluster, you must perform some configuration steps on the new hosts.
 
 There are different steps to follow depending on your PXF version and the type of installation.
 
-### PXF 5
-
-- You must install the same version of the PXF `rpm` or `deb` on the new hosts.
-- Log into the Cloudberry Coordinator and run the following commands:
-
-    ```shell
-    gpadmin@gpcoordinator$ pxf cluster reset
-    gpadmin@gpcoordinator$ pxf cluster init
-    ```
-
-
-### PXF 6
+### Apache Cloudberry PXF 2.x
 
 - You must install the same version of the PXF `rpm` or `deb` on the new hosts.
 - Log into the Cloudberry Coordinator and run the following commands:
@@ -52,5 +45,3 @@ There are different steps to follow depending on your PXF version and the type o
     gpadmin@gpcoordinator$ pxf cluster register
     gpadmin@gpcoordinator$ pxf cluster sync
     ```
-
-

docusaurus.config.ts

@@ -21,6 +21,18 @@ const config: Config = {
       "@easyops-cn/docusaurus-search-local",
       { hashed: true, indexPages: true, language: ["en"] },
     ],
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        id: 'pxf',
+        path: 'pxf/docs',
+        routeBasePath: 'pxf',
+        sidebarPath: './sidebarsPxf.ts',
+        editUrl: 'https://github.com/apache/cloudberry-pxf/edit/main/docs/',
+        // Exclude repo-level non-doc files from being rendered as pages
+        exclude: ['README.md'],
+      },
+    ],
   ],
 
   presets: [

scripts/setup-pxf-submodule.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+# Setup script for PXF submodule with sparse checkout
+# This script configures sparse checkout for the PXF submodule to only include docs/ directory
+
+set -e
+
+echo "Setting up PXF submodule with sparse checkout..."
+
+# Check if pxf directory exists
+if [ ! -d "pxf" ]; then
+    echo "ERROR: pxf directory not found. Please run 'git submodule update --init --recursive' first."
+    exit 1
+fi
+
+# Navigate to pxf directory
+cd pxf
+
+# Check if .git directory exists (it might be a file pointing to parent .git/modules)
+if [ -f ".git" ]; then
+    # It's a gitlink file, find the actual git directory
+    GITDIR=$(cat .git | sed 's/gitdir: //')
+    echo "Found git directory at: $GITDIR"
+
+    # Enable sparse checkout in the git module config
+    git config -f "$GITDIR/config" core.sparsecheckout true
+
+    # Create sparse-checkout file with docs/ pattern
+    mkdir -p "$(dirname "$GITDIR/info/sparse-checkout")"
+    echo "docs/" > "$GITDIR/info/sparse-checkout"
+
+    # Apply sparse checkout
+    git read-tree -mu HEAD
+
+    echo "Sparse checkout configured successfully!"
+    echo "Only 'docs/' directory will be checked out."
+
+    # Show what's actually in the directory
+    echo ""
+    echo "Current pxf directory contents:"
+    ls -la
+else
+    echo "ERROR: Could not find .git configuration in pxf directory"
+    exit 1
+fi
+
+echo ""
+echo "PXF submodule setup complete!"
+echo "The submodule now only contains the docs/ directory."

sidebars.ts

@@ -736,8 +736,12 @@ const sidebars: SidebarsConfig = {
           ],
         },
       ]
+    },
+    {
+      type: 'link',
+      label: 'Platform Extension Framework (PXF)',
+      href: '/pxf/',
     }
-
   ]
 }
 

sidebarsPxf.ts

@@ -0,0 +1,15 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
+/**
+ * PXF docs sidebar.
+ *
+ * This sidebar is consumed by the second docs plugin instance (id: 'pxf')
+ * which reads directly from the `pxf/docs` submodule.
+ */
+const sidebarsPxf: SidebarsConfig = {
+  pxfSidebar: [
+    {type: 'autogenerated', dirName: '.'},
+  ],
+};
+
+export default sidebarsPxf;

versioned_docs/version-2.x/sys-admin/expand-cluster/post-expansion-tasks.md

@@ -28,22 +28,15 @@ You can safely remove the expansion schema after the expansion operation is comp
 
 ## Set up PXF on the new host
 
+:::tip
+You can visit [PXF](/pxf) guides for more details.
+:::
+
 If you are using PXF in your Apache Cloudberry cluster, you must perform some configuration steps on the new hosts.
 
 There are different steps to follow depending on your PXF version and the type of installation.
 
-### PXF 5
-
-- You must install the same version of the PXF `rpm` or `deb` on the new hosts.
-- Log into the Cloudberry Coordinator and run the following commands:
-
-    ```shell
-    gpadmin@gpcoordinator$ pxf cluster reset
-    gpadmin@gpcoordinator$ pxf cluster init
-    ```
-
-
-### PXF 6
+### Apache Cloudberry PXF 2.x
 
 - You must install the same version of the PXF `rpm` or `deb` on the new hosts.
 - Log into the Cloudberry Coordinator and run the following commands:
@@ -53,4 +46,3 @@ There are different steps to follow depending on your PXF version and the type o
     gpadmin@gpcoordinator$ pxf cluster sync
     ```
 
-

versioned_sidebars/version-2.x-sidebars.json

@@ -790,6 +790,11 @@
           ]
         }
       ]
+    },
+    {
+      "type": "link",
+      "label": "Platform Extension Framework (PXF)",
+      "href": "/pxf/"
     }
   ]
 }