Docs: Fix duplicate search results by moving versioned docs out of docs_dir

.gitignore

@@ -25,7 +25,7 @@ lib/
 # web site build
 docs/site/
 site/site/
-site/docs/docs/
+site/versioned-docs/
 site/docs/.asf.yaml
 site/docs/javadoc/
 site/.venv/

site/README.md

@@ -36,22 +36,24 @@ In MkDocs, the [`docs_dir`](https://www.mkdocs.org/user-guide/configuration/#doc
 
 The static Iceberg website lives under the `/site` directory, while the versioned documentation lives under the `/docs` of the main Iceberg repository. The `/site/docs` directory is named that way to follow the [MkDocs convention](https://www.mkdocs.org/user-guide/configuration/#docs_dir). The `/docs` directory contains the current state of the versioned documentation with local revisions. Notice that the root `/site` and `/docs` just happened to share the same naming convention as MkDocs but does not correlate to the mkdocs.
 
-The static Iceberg site pages are Markdown files that live at `/site/docs/*.md`. The versioned documentation are Markdown files that live at `/docs/docs/*.md` files. You may ask where the older versions of the docs and javadocs are, which is covered later in the build section.
+The static Iceberg site pages are Markdown files that live at `/site/docs/*.md`. The versioned documentation are Markdown files that live at `/site/versioned-docs/<version>/docs/*.md` files. You may ask where the older versions of the docs and javadocs are, which is covered later in the build section.
 
 ```
 .
-├── docs (versioned)
-│   ├── docs
-│   │   ├── assets
-│   │   ├── api.md
-│   │   ├── ...
-│   │   └── table-migration.md
-│   └── mkdocs.yml
+├── versioned-docs (versioned, per version)
+│   ├── <version>
+│   │   ├── docs
+│   │   │   ├── assets
+│   │   │   ├── api.md
+│   │   │   ├── ...
+│   │   │   └── table-migration.md
+│   │   └── mkdocs.yml
+│   └── ...
 └── site (non-versioned)
     ├── docs
-    │   ├── about.md
-    │   ├── ...
-    │   └── view-spec.md
+    │   ├── about.md
+    │   ├── ...
+    │   └── view-spec.md
     ├── ...
     ├── Makefile
     ├── mkdocs.yml
@@ -62,7 +64,7 @@ The static Iceberg site pages are Markdown files that live at `/site/docs/*.md`.
 
 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 documentation source files (`/docs`) during release. These versions are mounted at the `/site/docs/docs/<version>` directory at build time.
+ 1. [`docs`](https://github.com/apache/iceberg/tree/docs) - contains the state of the documentation source files (`/docs`) during release. These versions are mounted at the `/site/versioned-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.
@@ -89,20 +91,21 @@ 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
-    │   └── ...
-    └─.asf.yaml
+├── versioned-docs
+│   ├── nightly (symlink to /docs/)
+│   ├── latest (symlink to versioned-docs/<latest-version>)
+│   ├── 1.4.0
+│   ├── 1.3.1
+│   └── ...
+├── docs
+│   ├── javadoc
+│   │   ├── nightly (currently points to latest)
+│   │   ├── latest
+│   │   ├── 1.4.0
+│   │   ├── 1.3.1
+│   │   └── ...
+│   └─.asf.yaml
+└── mkdocs.yml
 ```
 
 #### Linting
@@ -196,21 +199,21 @@ As mentioned in the MkDocs section, when you build MkDocs `mkdocs build`, MkDocs
 
 ```
 ./site/
+├── versioned-docs
+│   ├── nightly
+│   │   ├── docs
+│   │   └── mkdocs.yml
+│   ├── latest
+│   │   ├── docs
+│   │   └── mkdocs.yml
+│   └── 1.4.0
+│       ├── docs
+│       └── mkdocs.yml
 ├── docs
-│   ├── docs
-│   │   ├── nightly
-│   │   │   ├── docs
-│   │   │   └── mkdocs.yml
-│   │   ├── latest
-│   │   │   ├── docs
-│   │   │   └── mkdocs.yml
-│   │   └── 1.4.0
-│   │       ├── docs
-│   │       └── mkdocs.yml
-│   └─ javadoc
-│      ├── nightly
-│      ├── latest
-│      └── 1.4.0
+│   └─ javadoc
+│      ├── nightly
+│      ├── latest
+│      └── 1.4.0
 └── mkdocs.yml
 ```
 

site/dev/common.sh

@@ -71,14 +71,14 @@ create_nightly () {
   echo " --> create nightly"
 
   # Remove any existing 'nightly' directory and recreate it
-  rm -rf docs/docs/nightly/
-  mkdir docs/docs/nightly/
+  rm -rf versioned-docs/nightly/
+  mkdir versioned-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/
+  ln -s "../../../docs/docs/" versioned-docs/nightly/docs
+  cp "../docs/mkdocs.yml" versioned-docs/nightly/
 
-  cd docs/docs/
+  cd versioned-docs/
 
   # Update version information within the 'nightly' documentation
   update_version "nightly"  
@@ -118,14 +118,14 @@ create_latest () {
   echo "${ICEBERG_VERSION}"  
 
   # Remove any existing 'latest' directory and recreate it
-  rm -rf docs/docs/latest/
-  mkdir docs/docs/latest/
+  rm -rf versioned-docs/latest/
+  mkdir versioned-docs/latest/
 
   # Create symbolic links and copy configuration files for the 'latest' documentation
-  ln -s "../${ICEBERG_VERSION}/docs" docs/docs/latest/docs
-  cp "docs/docs/${ICEBERG_VERSION}/mkdocs.yml" docs/docs/latest/
+  ln -s "../${ICEBERG_VERSION}/docs" versioned-docs/latest/docs
+  cp "versioned-docs/${ICEBERG_VERSION}/mkdocs.yml" versioned-docs/latest/
 
-  cd docs/docs/
+  cd versioned-docs/
 
   # Update version information within the 'latest' documentation
   update_version "latest"  
@@ -188,15 +188,15 @@ pull_versioned_docs () {
     echo " --> This significantly reduces build time by skipping historical versions"
 
     # Create docs worktree with sparse checkout for latest version only
-    git worktree add --no-checkout -f docs/docs "${docs_branch}"
-    (cd docs/docs && git sparse-checkout init --cone && git sparse-checkout set "${latest_version}" && git checkout)
+    git worktree add --no-checkout -f versioned-docs "${docs_branch}"
+    (cd versioned-docs && git sparse-checkout init --cone && git sparse-checkout set "${latest_version}" && git checkout)
 
     # Create javadoc worktree with sparse checkout for latest version only
     git worktree add --no-checkout -f docs/javadoc "${javadoc_branch}"
     (cd docs/javadoc && git sparse-checkout init --cone && git sparse-checkout set "${latest_version}" && git checkout)
   else
     # Full checkout of all versions
-    git worktree add -f docs/docs "${docs_branch}"
+    git worktree add -f versioned-docs "${docs_branch}"
     git worktree add -f docs/javadoc "${javadoc_branch}"
   fi
 
@@ -229,14 +229,18 @@ clean () {
   set +e 
 
   # Remove temp directories and related Git worktrees
-  rm -rf docs/docs/latest &> /dev/null
-  rm -rf docs/docs/nightly &> /dev/null
+  rm -rf versioned-docs/latest &> /dev/null
+  rm -rf versioned-docs/nightly &> /dev/null
 
-  git worktree remove docs/docs &> /dev/null
+  git worktree remove versioned-docs &> /dev/null
   git worktree remove docs/javadoc &> /dev/null
 
+  # Clean up legacy layout (versioned docs used to live under docs/docs/)
+  rm -rf docs/docs/latest docs/docs/nightly &> /dev/null
+  git worktree remove docs/docs &> /dev/null
+
   # Remove any remaining artifacts
-  rm -rf docs/javadoc docs/docs docs/.asf.yaml site/
+  rm -rf docs/javadoc docs/docs versioned-docs docs/.asf.yaml site/
 
   set -e # Re-enable script exit on errors
 }

site/mkdocs-dev.yml

@@ -30,8 +30,8 @@ nav:
   - Docs:
     - Java:
       # First entry determines the default landing page for the Docs tab.
-      - Latest (1.10.1): '!include docs/docs/latest/mkdocs.yml'
-      - Nightly: '!include docs/docs/nightly/mkdocs.yml'
+      - Latest (1.10.2): '!include versioned-docs/latest/mkdocs.yml'
+      - Nightly: '!include versioned-docs/nightly/mkdocs.yml'
     - Other Implementations:
       - Python: https://py.iceberg.apache.org/
       - Rust: https://rust.iceberg.apache.org/
@@ -109,9 +109,6 @@ nav:
 
 exclude_docs: |
   !.asf.yaml
-  docs/
   javadoc/
-  !docs/nightly/
   !javadoc/nightly/
-  !docs/latest/
   !javadoc/latest/

site/nav.yml

@@ -24,28 +24,28 @@ nav:
   - Docs:
     - Java:
       # First entry determines the default landing page for the Docs tab.
-      - Latest (1.10.2): '!include docs/docs/latest/mkdocs.yml'
-      - Nightly: '!include docs/docs/nightly/mkdocs.yml'
+      - Latest (1.10.2): '!include versioned-docs/latest/mkdocs.yml'
+      - Nightly: '!include versioned-docs/nightly/mkdocs.yml'
       - Previous:
-        - 1.10.1: '!include docs/docs/1.10.1/mkdocs.yml'
-        - 1.10.0: '!include docs/docs/1.10.0/mkdocs.yml'
-        - 1.9.2: '!include docs/docs/1.9.2/mkdocs.yml'
-        - 1.9.1: '!include docs/docs/1.9.1/mkdocs.yml'
-        - 1.9.0: '!include docs/docs/1.9.0/mkdocs.yml'
-        - 1.8.1: '!include docs/docs/1.8.1/mkdocs.yml'
-        - 1.8.0: '!include docs/docs/1.8.0/mkdocs.yml'
-        - 1.7.2: '!include docs/docs/1.7.2/mkdocs.yml'
-        - 1.7.1: '!include docs/docs/1.7.1/mkdocs.yml'
-        - 1.7.0: '!include docs/docs/1.7.0/mkdocs.yml'
-        - 1.6.1: '!include docs/docs/1.6.1/mkdocs.yml'
-        - 1.6.0: '!include docs/docs/1.6.0/mkdocs.yml'
-        - 1.5.2: '!include docs/docs/1.5.2/mkdocs.yml'
-        - 1.5.1: '!include docs/docs/1.5.1/mkdocs.yml'
-        - 1.5.0: '!include docs/docs/1.5.0/mkdocs.yml'
-        - 1.4.3: '!include docs/docs/1.4.3/mkdocs.yml'
-        - 1.4.2: '!include docs/docs/1.4.2/mkdocs.yml'
-        - 1.4.1: '!include docs/docs/1.4.1/mkdocs.yml'
-        - 1.4.0: '!include docs/docs/1.4.0/mkdocs.yml'
+        - 1.10.1: '!include versioned-docs/1.10.1/mkdocs.yml'
+        - 1.10.0: '!include versioned-docs/1.10.0/mkdocs.yml'
+        - 1.9.2: '!include versioned-docs/1.9.2/mkdocs.yml'
+        - 1.9.1: '!include versioned-docs/1.9.1/mkdocs.yml'
+        - 1.9.0: '!include versioned-docs/1.9.0/mkdocs.yml'
+        - 1.8.1: '!include versioned-docs/1.8.1/mkdocs.yml'
+        - 1.8.0: '!include versioned-docs/1.8.0/mkdocs.yml'
+        - 1.7.2: '!include versioned-docs/1.7.2/mkdocs.yml'
+        - 1.7.1: '!include versioned-docs/1.7.1/mkdocs.yml'
+        - 1.7.0: '!include versioned-docs/1.7.0/mkdocs.yml'
+        - 1.6.1: '!include versioned-docs/1.6.1/mkdocs.yml'
+        - 1.6.0: '!include versioned-docs/1.6.0/mkdocs.yml'
+        - 1.5.2: '!include versioned-docs/1.5.2/mkdocs.yml'
+        - 1.5.1: '!include versioned-docs/1.5.1/mkdocs.yml'
+        - 1.5.0: '!include versioned-docs/1.5.0/mkdocs.yml'
+        - 1.4.3: '!include versioned-docs/1.4.3/mkdocs.yml'
+        - 1.4.2: '!include versioned-docs/1.4.2/mkdocs.yml'
+        - 1.4.1: '!include versioned-docs/1.4.1/mkdocs.yml'
+        - 1.4.0: '!include versioned-docs/1.4.0/mkdocs.yml'
         - archive: archive.md
     - Other Implementations:
       - Python: https://py.iceberg.apache.org/