diff --git a/.gitignore b/.gitignore index 98ccfc356d8b..5283f7013722 100644 --- a/.gitignore +++ b/.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/ diff --git a/site/README.md b/site/README.md index 212b0a706fd3..e14bb361d512 100644 --- a/site/README.md +++ b/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//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) +│ ├── +│ │ ├── 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/` 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/` 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/` 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/) +│ ├── 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 ``` diff --git a/site/dev/common.sh b/site/dev/common.sh index 6556a4df7637..6712d33c8b50 100755 --- a/site/dev/common.sh +++ b/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 } diff --git a/site/mkdocs-dev.yml b/site/mkdocs-dev.yml index 35526c5ec5b8..b5b98c983056 100644 --- a/site/mkdocs-dev.yml +++ b/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/ diff --git a/site/nav.yml b/site/nav.yml index 17bb73ef4f86..e38ef9af738d 100644 --- a/site/nav.yml +++ b/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/