From 67253c5c097cc81d7d45e71ed7bc27c2004806ce Mon Sep 17 00:00:00 2001 From: Dianjin Wang Date: Thu, 4 Jun 2026 18:02:41 +0800 Subject: [PATCH 1/5] Docs: integrate PXF documentation as multi-instance plugin - Add PXF submodule with sparse checkout for docs/ directory - Configure second docs plugin instance for PXF at /pxf route - Add PXF-specific sidebar configuration - Update README with submodule initialization instructions --- .gitmodules | 5 +++++ README.md | 12 +++++++++++- .../expand-cluster/post-expansion-tasks.md | 19 +++++-------------- docusaurus.config.ts | 12 ++++++++++++ pxf | 1 + sidebars.ts | 6 +++++- sidebarsPxf.ts | 15 +++++++++++++++ .../expand-cluster/post-expansion-tasks.md | 18 +++++------------- versioned_sidebars/version-2.x-sidebars.json | 5 +++++ 9 files changed, 64 insertions(+), 29 deletions(-) create mode 100644 .gitmodules create mode 160000 pxf create mode 100644 sidebarsPxf.ts diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000000..91e2bfb75d --- /dev/null +++ b/.gitmodules @@ -0,0 +1,5 @@ +[submodule "pxf"] + path = pxf + url = https://github.com/tuhaihe/cloudberry-pxf.git + branch = docs-update-for-site + sparse-checkout = docs/ diff --git a/README.md b/README.md index 2c1273e6ed..dd64088b56 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,17 @@ 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 +``` + +This will fetch the PXF documentation submodule with sparse checkout configured to only include the `docs/` directory. + +4. Build and run ``` $ npm run build diff --git a/docs/sys-admin/expand-cluster/post-expansion-tasks.md b/docs/sys-admin/expand-cluster/post-expansion-tasks.md index c8050bfe80..1e429e9aa3 100644 --- a/docs/sys-admin/expand-cluster/post-expansion-tasks.md +++ b/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 ``` - - diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 5282f6df0f..b5382f97dc 100644 --- a/docusaurus.config.ts +++ b/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: [ diff --git a/pxf b/pxf new file mode 160000 index 0000000000..32b1e79db4 --- /dev/null +++ b/pxf @@ -0,0 +1 @@ +Subproject commit 32b1e79db405bfb672cb272fae4d0af564017c08 diff --git a/sidebars.ts b/sidebars.ts index 4d8f29e0f8..935fe8dbc5 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -736,8 +736,12 @@ const sidebars: SidebarsConfig = { ], }, ] + }, + { + type: 'link', + label: 'Platform Extension Framework (PXF)', + href: '/pxf/', } - ] } diff --git a/sidebarsPxf.ts b/sidebarsPxf.ts new file mode 100644 index 0000000000..e44dd47c19 --- /dev/null +++ b/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; diff --git a/versioned_docs/version-2.x/sys-admin/expand-cluster/post-expansion-tasks.md b/versioned_docs/version-2.x/sys-admin/expand-cluster/post-expansion-tasks.md index c8050bfe80..e2686266db 100644 --- a/versioned_docs/version-2.x/sys-admin/expand-cluster/post-expansion-tasks.md +++ b/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 ``` - diff --git a/versioned_sidebars/version-2.x-sidebars.json b/versioned_sidebars/version-2.x-sidebars.json index 82d0d2f987..6f79621b60 100644 --- a/versioned_sidebars/version-2.x-sidebars.json +++ b/versioned_sidebars/version-2.x-sidebars.json @@ -790,6 +790,11 @@ ] } ] + }, + { + "type": "link", + "label": "Platform Extension Framework (PXF)", + "href": "/pxf/" } ] } \ No newline at end of file From 759becb17202dee0eed45e7a44e6e90efaca1b43 Mon Sep 17 00:00:00 2001 From: Dianjin Wang Date: Thu, 4 Jun 2026 18:05:47 +0800 Subject: [PATCH 2/5] Add submodule to workflow --- .github/workflows/publish-cloudberry-site.yml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.github/workflows/publish-cloudberry-site.yml b/.github/workflows/publish-cloudberry-site.yml index 144bb3f62b..402db28b1c 100644 --- a/.github/workflows/publish-cloudberry-site.yml +++ b/.github/workflows/publish-cloudberry-site.yml @@ -49,6 +49,8 @@ jobs: contents: write steps: - uses: actions/checkout@v4 + with: + submodules: 'recursive' - uses: actions/setup-node@v4 with: node-version: 20 @@ -56,6 +58,12 @@ jobs: # 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" - name: Build site run: | From 5ea58a26434111235dcefe1c31c9c0e7b12af56a Mon Sep 17 00:00:00 2001 From: Dianjin Wang Date: Thu, 4 Jun 2026 18:15:10 +0800 Subject: [PATCH 3/5] Update bash file --- .github/workflows/publish-cloudberry-site.yml | 14 +++++- README.md | 3 +- scripts/setup-pxf-submodule.sh | 49 +++++++++++++++++++ 3 files changed, 63 insertions(+), 3 deletions(-) create mode 100755 scripts/setup-pxf-submodule.sh diff --git a/.github/workflows/publish-cloudberry-site.yml b/.github/workflows/publish-cloudberry-site.yml index 402db28b1c..29f35ff6e3 100644 --- a/.github/workflows/publish-cloudberry-site.yml +++ b/.github/workflows/publish-cloudberry-site.yml @@ -61,9 +61,19 @@ jobs: - name: Initialize submodules run: | - echo "📦 Initializing git submodules..." + echo "Initializing git submodules..." git submodule update --init --recursive - echo "✅ Submodules initialized" + 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: | diff --git a/README.md b/README.md index dd64088b56..b16a07d272 100644 --- a/README.md +++ b/README.md @@ -79,9 +79,10 @@ This repository uses git submodules to include PXF documentation. After cloning, ``` $ git submodule update --init --recursive +$ ./scripts/setup-pxf-submodule.sh ``` -This will fetch the PXF documentation submodule with sparse checkout configured to only include the `docs/` directory. +The setup script configures sparse checkout to only include the `docs/` directory from the PXF submodule. 4. Build and run diff --git a/scripts/setup-pxf-submodule.sh b/scripts/setup-pxf-submodule.sh new file mode 100755 index 0000000000..c0916a3956 --- /dev/null +++ b/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." \ No newline at end of file From 7f2d50d34f247bedefd6f88be04df53e4a6db7c8 Mon Sep 17 00:00:00 2001 From: Dianjin Wang Date: Tue, 9 Jun 2026 15:26:28 +0800 Subject: [PATCH 4/5] chore: update PXF submodule to latest commit (e400febd) - Update PXF submodule reference to e400febd8544936961caa7841b71f532503974b2 - Includes fixes for broken links in PXF documentation --- pxf | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pxf b/pxf index 32b1e79db4..e400febd85 160000 --- a/pxf +++ b/pxf @@ -1 +1 @@ -Subproject commit 32b1e79db405bfb672cb272fae4d0af564017c08 +Subproject commit e400febd8544936961caa7841b71f532503974b2 From c82ca2e194bf96f68cc4084aa848cceb22fbcd21 Mon Sep 17 00:00:00 2001 From: Dianjin Wang Date: Tue, 9 Jun 2026 15:51:49 +0800 Subject: [PATCH 5/5] chore: switch PXF submodule to official Apache repository - Update .gitmodules to point to https://github.com/apache/cloudberry-pxf.git - Update submodule reference to commit dff2632d from official repo - Includes latest documentation updates for cloudberry-site integration --- .gitmodules | 5 ++--- pxf | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.gitmodules b/.gitmodules index 91e2bfb75d..efc1b29e4c 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,5 +1,4 @@ [submodule "pxf"] path = pxf - url = https://github.com/tuhaihe/cloudberry-pxf.git - branch = docs-update-for-site - sparse-checkout = docs/ + url = https://github.com/apache/cloudberry-pxf.git + sparse-checkout = docs/ \ No newline at end of file diff --git a/pxf b/pxf index e400febd85..dff2632d2a 160000 --- a/pxf +++ b/pxf @@ -1 +1 @@ -Subproject commit e400febd8544936961caa7841b71f532503974b2 +Subproject commit dff2632d2a364f466b83682439c3ae97e655c1b7