This is an automated email from the ASF dual-hosted git repository.
lhotari pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new eaafd17d4b7c Improve site preview instructions
eaafd17d4b7c is described below
commit eaafd17d4b7ca39b6379738761b36ec4595b9649
Author: Lari Hotari <[email protected]>
AuthorDate: Tue Oct 29 14:04:07 2024 +0200
Improve site preview instructions
---
contribute/document-preview.md | 26 ++++++++++++++++++--------
contribute/site-intro.md | 8 +++++++-
preview.sh | 33 +++++++++++++++++++++++++++++----
3 files changed, 54 insertions(+), 13 deletions(-)
diff --git a/contribute/document-preview.md b/contribute/document-preview.md
index 437ec8262451..e047416b9ac1 100644
--- a/contribute/document-preview.md
+++ b/contribute/document-preview.md
@@ -21,16 +21,23 @@ To verify docs are built correctly before submitting a
contribution, you should
* Corepack available and enabled (`corepack enable`)
* Although you can use Linux, macOS, or Windows to build locally the Pulsar
documentation, macOS is the preferred build environment as it offers the most
complete support for documentation building.
-Installing prerequisites with [homebrew](https://brew.sh/) on MacOS or Linux:
+Installing prerequisites with [Homebrew](https://brew.sh/) on macOS or Linux:
```shell
brew install node
-brew install corepack || brew link corepack
corepack enable
```
-Sometimes homebrew has corepack installed, but it's not available. In that
case, `brew link corepack` fixes the problem.
-Don't install `yarn` separately since it's part of `corepack`.
+#### Troubleshooting Corepack installation - Homebrew installations on macOS
or Linux
+
+Sometimes Homebrew has Corepack installed, but it's not available. You might
need to run `brew unlink node; brew link node; corepack enable` to fix the
installation.
+Please also ensure that you have upgraded Homebrew packages to the latest
versions. Run `brew upgrade` to upgrade all installed packages.
+
+Don't install `yarn` separately from a package manager since it's included
with `corepack`, which is bundled with `node`. If you're using Homebrew,
uninstall any existing `yarn` installation with `brew uninstall yarn` to avoid
conflicts.
+
+If `corepack enable` fails due to file conflicts, verify that no legacy
`corepack` or `yarn` package is already installed. If found, remove them.
Removing `corepack` on updated Homebrew installations is not recommended since
it uninstalls `node`.
+
+If issues persist, run `brew unlink node; brew link node; corepack enable`. If
`corepack enable` continues to fail due to conflicting files, manually remove
the conflicting files from `/opt/homebrew/bin` and try again.
### Preview changes
@@ -54,16 +61,19 @@ Follow these steps to preview the website changes.
2. Run the following command to preview changes:
```bash
- # Preview changes on master
- ./preview.sh current
+ # Preview changes on master (next version documentation)
+ ./preview.sh
# preview changes on a specific version
- ./preview.sh 2.10.x
+ ./preview.sh 4.0.x
# preview changes on multiple versions
- ./preview.sh 2.10.x 2.9.x ...
+ ./preview.sh 4.0.x 3.0.x current
```
+If you have content staleness issues, you can pass the `--clean` (or `-c`)
flag to the `preview.sh` script to clean Docusaurus cache and start a fresh
build.
+This runs `yarn run docusaurus clear` before starting the preview server.
+
By default, a browser window will open at
[http://localhost:3000](http://localhost:3000) to show the changes:
diff --git a/contribute/site-intro.md b/contribute/site-intro.md
index 9c78b853d2ba..fabd9b89fe62 100644
--- a/contribute/site-intro.md
+++ b/contribute/site-intro.md
@@ -33,7 +33,13 @@ Besides, the site serves multiple static pages generated
outside the framework,
The most commonly used tool is `preview.sh`. You can preview your local
changes by:
```shell
-./preview.sh 2.11.x
+./preview.sh
+```
+
+If you'd like to preview the site for a specific versions, you can pass the
versions as an argument:
+
+```shell
+./preview.sh 4.0.x
```
See the [previewing content](document-preview.md) guide for more details.
diff --git a/preview.sh b/preview.sh
index 8c25e7d75f64..fe7a5c97c255 100755
--- a/preview.sh
+++ b/preview.sh
@@ -1,4 +1,14 @@
-#! /bin/sh
+#!/bin/bash
+if [[ "$1" == "help" || "$1" == "--help" ]]; then
+ echo "Usage: ./preview.sh [--clean] [version1] [version2] [version3]"
+ exit 0
+fi
+
+if [[ "$1" == "--clean" || "$1" == "-c" ]]; then
+ shift
+ CLEAN=true
+fi
+
BUILD_VERSIONS="[\"current\""
for version in $@; do
BUILD_VERSIONS=$BUILD_VERSIONS", \""$version"\""
@@ -7,12 +17,27 @@ BUILD_VERSIONS=$BUILD_VERSIONS"]"
echo $BUILD_VERSIONS >.build-versions.json
-if ! command -v yarn &>/dev/null; then
- echo "yarn is not available. yarn comes with corepack, with homebrew you
can install it by running:"
- echo "brew install corepack || brew link corepack"
+show_yarn_installation_help() {
+ echo "yarn is not available. yarn comes with corepack. corepack is part of
the node runtime package in Homebrew."
+ echo "You will need to activate corepack by running:"
echo "corepack enable"
+ echo "Don't install yarn separately from a package manager. With Homebrew,
uninstall any existing yarn installation with 'brew uninstall yarn'"
+ echo "You might have to run 'brew unlink node; brew link node; corepack
enable' to fix the installation."
+ echo "If 'corepack enable' fails due to file conflicts, remove the
conflictings files manually from /opt/homebrew/bin and try again."
+}
+
+if ! command -v yarn &>/dev/null; then
+ show_yarn_installation_help
exit 1
fi
+yarn help 2>&1 >/dev/null || {
+ show_yarn_installation_help
+ exit 1
+}
+
yarn install
+if [[ "$CLEAN" == true ]]; then
+ yarn run docusaurus clear
+fi
yarn start
