diff --git a/site/README.md b/site/README.md index 63394635b463..6cb4f4907ebf 100644 --- a/site/README.md +++ b/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/` 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/` 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/` 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. 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,6 +150,9 @@ As mentioned in the MkDocs section, when you build MkDocs `mkdocs build`, MkDocs ./site/ ├── docs │   ├── docs +│   │   ├── nightly +│   │   │ ├── docs +│   │   │ └── mkdocs.yml │   │   ├── latest │   │   │ ├── docs │   │   │ └── mkdocs.yml @@ -150,6 +160,7 @@ As mentioned in the MkDocs section, when you build MkDocs `mkdocs build`, MkDocs │   │   ├── docs │   │ └── mkdocs.yml │   └─ javadoc +│   ├── nightly │   ├── latest │   └── 1.4.0 └── mkdocs.yml diff --git a/site/dev/common.sh b/site/dev/common.sh index 6eb0cf34a9c0..481628aa4dbd 100755 --- a/site/dev/common.sh +++ b/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 diff --git a/site/nav.yml b/site/nav.yml index aa5c77b46122..4a3548433636 100644 --- a/site/nav.yml +++ b/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'