diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a5384acb6..34bf1e514 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -159,7 +159,7 @@ jobs: gh release upload ${{ needs.release-drafter.outputs.tag_name }} .artifacts/publish/docs-builder/release/*.zip gh release upload ${{ needs.release-drafter.outputs.tag_name }} .artifacts/publish/docs-assembler/release/*.zip shell: bash - + publish-release: needs: - release diff --git a/docs/contribute/locally.md b/docs/contribute/locally.md index 81963a460..c499984ef 100644 --- a/docs/contribute/locally.md +++ b/docs/contribute/locally.md @@ -30,44 +30,43 @@ This guide uses the first option. If you'd like to clone the repository and buil :::{tab-item} macOS -1. **Download the Binary:** - Download the latest macOS binary from [releases](https://github.com/elastic/docs-builder/releases/latest/): - ```sh - curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip - ``` +1. **Download and run the install script** + + Run this command to download and install the latest version of `docs-builder`: -2. **Extract the Binary:** - Unzip the downloaded file: ```sh - unzip docs-builder-mac-arm64.zip + sudo curl -L https://raw.githubusercontent.com/elastic/docs-builder/refs/heads/main/install.sh | sh ``` + This downloads the latest binary, makes it executable, and installs it to your user PATH. + +2. **Run docs-builder from a docs folder** + + Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`: -3. **Run the Binary:** - Use the `serve` command to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`: ```sh - ./docs-builder serve -p ./path/to/docs + docs-builder serve ``` ::: :::{tab-item} Windows -1. **Download the Binary:** - Download the latest Windows binary from [releases](https://github.com/elastic/docs-builder/releases/latest/): - ```sh - Invoke-WebRequest -Uri https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip -OutFile docs-builder-win-x64.zip - ``` +1. **Download and run the install script** -2. **Extract the Binary:** - Unzip the downloaded file. You can use tools like WinZip, 7-Zip, or the built-in Windows extraction tool. - ```sh - Expand-Archive -Path docs-builder-win-x64.zip -DestinationPath . + Run this command to download and install the latest version of `docs-builder`: + + ```powershell + iex (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/elastic/docs-builder/refs/heads/main/install.ps1') ``` -3. **Run the Binary:** - Use the `serve` command to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`: + This downloads the latest binary, makes it executable, and installs it to your user PATH. + +2. **Run docs-builder from a docs folder** + + Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`: + ```sh - .\docs-builder serve -p ./path/to/docs + docs-builder serve ``` ::: diff --git a/install.ps1 b/install.ps1 new file mode 100755 index 000000000..f410dee38 --- /dev/null +++ b/install.ps1 @@ -0,0 +1,60 @@ +# PowerShell script to install docs-builder binary + +# Use AppData\Local for user-specific installation instead of Program Files +$targetDir = Join-Path -Path $env:LOCALAPPDATA -ChildPath "docs-builder" +$targetPath = Join-Path -Path $targetDir -ChildPath "docs-builder.exe" + +# Check if docs-builder already exists +if (Test-Path -Path $targetPath) { + Write-Host "docs-builder is already installed." + $choice = Read-Host -Prompt "Do you want to update/overwrite it? (y/n)" + switch ($choice.ToLower()) { + 'y' { Write-Host "Updating docs-builder..." } + 'n' { Write-Host "Installation aborted."; exit 0 } + Default { Write-Host "Invalid choice. Installation aborted."; exit 1 } + } +} + +# Create target directory if it doesn't exist +if (-not (Test-Path -Path $targetDir)) { + New-Item -ItemType Directory -Path $targetDir -Force | Out-Null +} + +# Download the latest Windows binary from releases +$tempZipPath = "$env:TEMP\docs-builder-win-x64.zip" +Write-Host "Downloading docs-builder binary..." +Invoke-WebRequest -Uri "https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip" -OutFile $tempZipPath + +# Create a temporary directory for extraction +$tempExtractPath = "$env:TEMP\docs-builder-extract" +if (Test-Path -Path $tempExtractPath) { + Remove-Item -Path $tempExtractPath -Recurse -Force +} +New-Item -ItemType Directory -Path $tempExtractPath -Force | Out-Null + +# Extract the binary +Write-Host "Extracting binary..." +Expand-Archive -Path $tempZipPath -DestinationPath $tempExtractPath -Force + +# Copy the executable to the target location +Write-Host "Installing docs-builder..." +Copy-Item -Path "$tempExtractPath\docs-builder.exe" -Destination $targetPath -Force + +# Add to PATH if not already in PATH (using User scope instead of Machine) +$currentPath = [Environment]::GetEnvironmentVariable("PATH", [EnvironmentVariableTarget]::User) +if ($currentPath -notlike "*$targetDir*") { + Write-Host "Adding docs-builder to the user PATH..." + [Environment]::SetEnvironmentVariable( + "PATH", + "$currentPath;$targetDir", + [EnvironmentVariableTarget]::User + ) + $env:PATH = "$env:PATH;$targetDir" +} + +# Clean up temporary files +Remove-Item -Path $tempZipPath -Force +Remove-Item -Path $tempExtractPath -Recurse -Force + +Write-Host "docs-builder has been installed successfully and is available in your PATH." +Write-Host "You may need to restart your terminal or PowerShell session for the PATH changes to take effect." \ No newline at end of file diff --git a/install.sh b/install.sh new file mode 100755 index 000000000..dc6332a1a --- /dev/null +++ b/install.sh @@ -0,0 +1,72 @@ +#!/bin/sh +set -e + +# Determine OS type and architecture +OS=$(uname -s | tr '[:upper:]' '[:lower:]') +ARCH=$(uname -m) + +# Map architecture naming +if [ "$ARCH" = "x86_64" ]; then + ARCH="amd64" +elif [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then + ARCH="arm64" +fi + +# Determine binary to download based on OS +if [ "$OS" = "darwin" ]; then + BINARY="docs-builder-mac-$ARCH.zip" + DEFAULT_INSTALL_DIR="/usr/local/bin" +elif [ "$OS" = "linux" ]; then + BINARY="docs-builder-linux-$ARCH.zip" + DEFAULT_INSTALL_DIR="/usr/local/bin" +else + echo "Unsupported operating system: $OS" + exit 1 +fi + +# Determine if we need sudo for the install directory +INSTALL_DIR="$DEFAULT_INSTALL_DIR" +if [ ! -w "$INSTALL_DIR" ]; then + USE_SUDO=true + echo "Note: Installing to $INSTALL_DIR requires administrator privileges." +else + USE_SUDO=false +fi + +# Check if docs-builder already exists +if [ -f "$INSTALL_DIR/docs-builder" ]; then + echo "docs-builder is already installed." + printf "Do you want to update/overwrite it? (y/n): " + read choice + case "$choice" in + y|Y ) echo "Updating docs-builder..." ;; + n|N ) echo "Installation aborted."; exit 0 ;; + * ) echo "Invalid choice. Installation aborted."; exit 1 ;; + esac +fi + +echo "Downloading docs-builder for $OS/$ARCH..." + +# Download the appropriate binary +curl -LO "https://github.com/elastic/docs-builder/releases/latest/download/$BINARY" + +# Extract only the docs-builder file to /tmp directory +# Use -o flag to always overwrite files without prompting +unzip -j -o "$BINARY" docs-builder -d /tmp + +# Ensure the binary is executable +chmod +x /tmp/docs-builder + +# Move the binary to the install directory +echo "Installing docs-builder to $INSTALL_DIR..." +if [ "$USE_SUDO" = true ]; then + sudo mv -f /tmp/docs-builder "$INSTALL_DIR/docs-builder" +else + mv -f /tmp/docs-builder "$INSTALL_DIR/docs-builder" +fi + +# Clean up the downloaded zip file +rm -f "$BINARY" + +echo "docs-builder has been installed successfully and is available in your PATH." +echo "You can run 'docs-builder --help' to see available commands." \ No newline at end of file