This is an automated email from the ASF dual-hosted git repository.
etudenhoefner pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg.git
The following commit(s) were added to refs/heads/main by this push:
new 3cd82a7e99 Docs, Infra: Mount local versioned doc branch for testing
(#10838)
3cd82a7e99 is described below
commit 3cd82a7e996db0bfb2cdc599d5dea3ada04f51aa
Author: gaborkaszab <[email protected]>
AuthorDate: Tue Aug 13 12:58:48 2024 +0200
Docs, Infra: Mount local versioned doc branch for testing (#10838)
The versioned docs are pulled from the remote 'iceberg_docs' repo. When
making local changes to versioned docs it seems reasonable to mount some
local git branch instead of the remote one so that we can test the
changes.
This patch add support for setting a local branch to be mounted for the
versioned docs using environment variables.
---
site/README.md | 10 ++++++++++
site/dev/common.sh | 9 ++++++---
2 files changed, 16 insertions(+), 3 deletions(-)
diff --git a/site/README.md b/site/README.md
index 39bc1d931b..97ddddc5cd 100644
--- a/site/README.md
+++ b/site/README.md
@@ -113,6 +113,16 @@ To clear all build files, run `clean`.
make clean
```
+#### Testing local changes on versioned docs
+
+When you build the docs as described above, by default the versioned docs are
mounted from the upstream remote repositiory called `iceberg_docs`. One
exception is the `nightly` version that is a soft link to the local `docs/`
folder.
+
+When you make changes to some of the historical versioned docs in a local git
branch you can mount this git branch instead of the remote one by setting the
following environment variables:
+
+`ICEBERG_VERSIONED_DOCS_BRANCH` for the `docs/` folder
+
+`ICEBERG_VERSIONED_JAVADOC_BRANCH` for the `javadoc/` folder
+
#### Offline mode
One of the great advantages to the MkDocs material plugin is the [offline
feature](https://squidfunk.github.io/mkdocs-material/plugins/offline). You can
view the Iceberg docs without the need of a server. To enable OFFLINE builds,
add theOFFLINE environment variable to either `build` or `serve` recipes.
diff --git a/site/dev/common.sh b/site/dev/common.sh
index 481628aa4d..6fc045560f 100755
--- a/site/dev/common.sh
+++ b/site/dev/common.sh
@@ -197,9 +197,12 @@ pull_versioned_docs () {
# Ensure the remote repository for documentation exists and is up-to-date
create_or_update_docs_remote
- # Add local worktrees for documentation and javadoc from the remote
repository
- git worktree add -f docs/docs "${REMOTE}/docs"
- git worktree add -f docs/javadoc "${REMOTE}/javadoc"
+ # Add local worktrees for documentation and javadoc either from the remote
repository
+ # or from a local branch.
+ local docs_branch="${ICEBERG_VERSIONED_DOCS_BRANCH:-${REMOTE}/docs}"
+ local javadoc_branch="${ICEBERG_VERSIONED_JAVADOC_BRANCH:-${REMOTE}/javadoc}"
+ git worktree add -f docs/docs "${docs_branch}"
+ git worktree add -f docs/javadoc "${javadoc_branch}"
# Retrieve the latest version of documentation for processing
local latest_version=$(get_latest_version)
