Add local nightly build to test current docs changes

site/README.md

@@ -60,7 +60,12 @@ The static Iceberg site pages are Markdown files that live at `/site/docs/*.md`.
 ```
 ### Building the versioned docs
 
-The Iceberg versioned docs are committed in the [orphan `docs` branch](https://github.com/apache/iceberg/tree/docs) and mounted using [git worktree](https://git-scm.com/docs/git-worktree) at build time. The `docs` branch contains the versioned documenation source files at the root. These versions are mounted at the `/site/docs/docs/<version>` directory at build time. The `latest` version, is a soft link to the most recent [semver version](https://semver.org/) in the `docs` branch. There is also an [orphan `javadoc` branch](https://github.com/apache/iceberg/tree/javadoc) that contains prior staticly generated versions of the javadocs mounted at `/site/docs/javadoc/<version>` during build time.
+The Iceberg versioned docs are committed in two [orphan](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeforphanaorphan) branches and mounted using [git worktree](https://git-scm.com/docs/git-worktree) at build time: 
+
+ 1. [`docs`](https://github.com/apache/iceberg/tree/docs) - contains the state of the documenation source files (`/docs`) during release. These versions are mounted at the `/site/docs/docs/<version>` directory at build time. 
+ 1. [`javadoc`](https://github.com/apache/iceberg/tree/javadoc) - contains prior statically generated versions of the javadocs mounted at `/site/docs/javadoc/<version>` directory at  build time.
+
+The `latest` version, is a soft link to the most recent [semver version](https://semver.org/) in the `docs` branch. The `nightly` version, is a soft link to the current local state of the `/docs` markdown files.
 
 The docs are built, run, and released using [make](https://www.gnu.org/software/make/manual/make.html). The [Makefile](Makefile) and the [common shell script](dev/common.sh) support the following command:
 
@@ -84,11 +89,13 @@ This step will generate the staged source code which blends into the original so
 ./site/
 └── docs
     ├── docs
+    │   ├── nightly (symlink to /docs/)
     │   ├── latest (symlink to /site/docs/1.4.0/)
     │   ├── 1.4.0 
     │   ├── 1.3.1
     │   └── ...
     ├── javadoc
+    │   ├── nightly (currently points to latest)
     │   ├── latest
     │   ├── 1.4.0
     │   ├── 1.3.1
@@ -143,13 +150,17 @@ As mentioned in the MkDocs section, when you build MkDocs `mkdocs build`, MkDocs
 ./site/
 ├── docs
 │   ├── docs
+│   │   ├── nightly
+│   │   │   ├── docs
+│   │   │   └── mkdocs.yml
 │   │   ├── latest
 │   │   │   ├── docs
 │   │   │   └── mkdocs.yml
 │   │   └── 1.4.0
 │   │       ├── docs
 │   │       └── mkdocs.yml
 │   └─ javadoc
+│      ├── nightly 
 │      ├── latest
 │      └── 1.4.0
 └── mkdocs.yml

site/dev/common.sh

@@ -85,6 +85,26 @@ assert_not_empty () {
   fi
 }
 
+# Creates a 'nightly' version of the documentation that points to the current versioned docs
+# located at the root-level `/docs` directory.
+create_nightly () {
+  echo " --> create nightly"
+
+  # Remove any existing 'nightly' directory and recreate it
+  rm -rf docs/docs/nightly/
+  mkdir docs/docs/nightly/
+
+  # Create symbolic links and copy configuration files for the 'nightly' documentation
+  ln -s "../../../../docs/docs/" docs/docs/nightly/docs
+  cp "../docs/mkdocs.yml" docs/docs/nightly/
+
+  cd docs/docs/
+
+  # Update version information within the 'nightly' documentation
+  update_version "nightly"  
+  cd -
+}
+
 # Finds and retrieves the latest version of the documentation based on the directory structure.
 # Assumes the documentation versions are numeric folders within 'docs/docs/'.
 get_latest_version () {
@@ -189,6 +209,9 @@ pull_versioned_docs () {
 
   # Create the 'latest' version of documentation
   create_latest "${latest_version}"  
+
+  # Create the 'nightly' version of documentation
+  create_nightly  
 }
 
 # Cleans up artifacts and temporary files generated during documentation management.
@@ -198,8 +221,9 @@ clean () {
   # Temporarily disable script exit on errors to ensure cleanup continues
   set +e 
 
-  # Remove 'latest' directories and related Git worktrees
+  # Remove temp directories and related Git worktrees
   rm -rf docs/docs/latest &> /dev/null
+  rm -rf docs/docs/nightly &> /dev/null
 
   git worktree remove docs/docs &> /dev/null
   git worktree remove docs/javadoc &> /dev/null

site/nav.yml

@@ -21,6 +21,7 @@ nav:
     - Spark: spark-quickstart.md
     - Hive: hive-quickstart.md
   - Docs: 
+    - nightly: '!include docs/docs/nightly/mkdocs.yml'
     - latest: '!include docs/docs/latest/mkdocs.yml'
     - 1.5.0: '!include docs/docs/1.5.0/mkdocs.yml'
     - 1.4.3: '!include docs/docs/1.4.3/mkdocs.yml'