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 c9795fda71 Docs: Add local nightly build to test current docs changes
(#9943)
c9795fda71 is described below
commit c9795fda7105789edc0d1f8a624ceb251dfd4a69
Author: Brian "bits" Olsen <[email protected]>
AuthorDate: Fri Mar 22 02:23:36 2024 -0500
Docs: Add local nightly build to test current docs changes (#9943)
---
site/README.md | 13 ++++++++++++-
site/dev/common.sh | 26 +++++++++++++++++++++++++-
site/nav.yml | 1 +
3 files changed, 38 insertions(+), 2 deletions(-)
diff --git a/site/README.md b/site/README.md
index 63394635b4..6cb4f4907e 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/<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 [...]
+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,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 6eb0cf34a9..481628aa4d 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 aa5c77b461..4a35484336 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'
