This is an automated email from the ASF dual-hosted git repository.
tuhaihe pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudberry-site.git
The following commit(s) were added to refs/heads/main by this push:
new f692dbb047 Docs: integrate PXF documentation as multi-instance plugin
(#372)
f692dbb047 is described below
commit f692dbb0472bc4816e74a658297f9a922130b729
Author: Dianjin Wang <[email protected]>
AuthorDate: Tue Jun 9 16:00:29 2026 +0800
Docs: integrate PXF documentation as multi-instance plugin (#372)
- 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
- Add submodule to workflow
---
.github/workflows/publish-cloudberry-site.yml | 18 ++++++++
.gitmodules | 4 ++
README.md | 13 +++++-
.../expand-cluster/post-expansion-tasks.md | 19 +++------
docusaurus.config.ts | 12 ++++++
pxf | 1 +
scripts/setup-pxf-submodule.sh | 49 ++++++++++++++++++++++
sidebars.ts | 6 ++-
sidebarsPxf.ts | 15 +++++++
.../expand-cluster/post-expansion-tasks.md | 18 +++-----
versioned_sidebars/version-2.x-sidebars.json | 5 +++
11 files changed, 131 insertions(+), 29 deletions(-)
diff --git a/.github/workflows/publish-cloudberry-site.yml
b/.github/workflows/publish-cloudberry-site.yml
index 144bb3f62b..29f35ff6e3 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,22 @@ 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"
+
+ # 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/.gitmodules b/.gitmodules
new file mode 100644
index 0000000000..efc1b29e4c
--- /dev/null
+++ b/.gitmodules
@@ -0,0 +1,4 @@
+[submodule "pxf"]
+ path = pxf
+ url = https://github.com/apache/cloudberry-pxf.git
+ sparse-checkout = docs/
\ No newline at end of file
diff --git a/README.md b/README.md
index 2c1273e6ed..b16a07d272 100644
--- a/README.md
+++ b/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
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..dff2632d2a
--- /dev/null
+++ b/pxf
@@ -0,0 +1 @@
+Subproject commit dff2632d2a364f466b83682439c3ae97e655c1b7
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
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
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
