diff --git a/rebuild-docs.ps1 b/rebuild-docs.ps1 index defb230ad..7ab015b45 100644 --- a/rebuild-docs.ps1 +++ b/rebuild-docs.ps1 @@ -1,491 +1,492 @@ #!/usr/bin/env pwsh # Rebuild-docs # # Rebuilds the documentation for DSharpPlus NextGen project, and places artifacts in specified directory. -# +# # Author: Emzi0767 # Version: 2017-09-11 14:20 # # Arguments: # .\rebuild-docs.ps1 # # Run as: # .\rebuild-docs.ps1 .\path\to\docfx\project .\path\to\output project-docs param ( [parameter(Mandatory = $true)] [string] $DocsPath, - + [parameter(Mandatory = $true)] [string] $OutputPath, - + [parameter(Mandatory = $true)] [string] $PackageName ) # Backup the environment $current_path = $Env:PATH $current_location = Get-Location # Tool paths $docfx_path = Join-Path "$current_location" "docfx" $sevenzip_path = Join-Path "$current_location" "7zip" # Restores the environment function Restore-Environment() { Write-Host "Restoring environment variables" $Env:PATH = $current_path Set-Location -path "$current_location" - + if (Test-Path "$docfx_path") { Remove-Item -recurse -force "$docfx_path" } - + if (Test-Path "$sevenzip_path") { Remove-Item -recurse -force "$sevenzip_path" } } # Downloads and installs latest version of DocFX function Install-DocFX([string] $target_dir_path) { Write-Host "Installing DocFX" # Check if the target directory exists # If it does, remove it if (Test-Path "$target_dir_path") { Write-Host "Target directory exists, deleting" Remove-Item -recurse -force "$target_dir_path" } - + # Create target directory $target_dir = New-Item -type directory "$target_dir_path" $target_fn = "docfx.zip" - + # Form target path $target_dir = $target_dir.FullName $target_path = Join-Path "$target_dir" "$target_fn" - + # Download release info from Chocolatey API try { Write-Host "Getting latest DocFX release" $release_json = Invoke-WebRequest -uri "https://chocolatey.org/api/v2/package-versions/docfx" | ConvertFrom-JSON $release_json = $release_json | % { [System.Version]::Parse($_) } | Sort-Object -Descending } catch { Return 1 } - + # Set TLS version to 1.2 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 - + # Download the release # Since GH releases are unreliable, we have to try up to 3 times $tries = 0 $fail = $true while ($tries -lt 3) { # Prepare the assets $release = $release_json[$tries] # Pick the next available release - $release_version = $release.ToString() # Convert to string + #$release_version = $release.ToString() # Convert to string + $release_version = "2.58.5" $release_asset = "https://github.com/dotnet/docfx/releases/download/v$release_version/docfx.zip" - + # increment try counter $tries = $tries + 1 - + try { Write-Host "Downloading DocFX $release_version to $target_path" Invoke-WebRequest -uri "$release_asset" -outfile "$target_path" - + # No failure, carry on Write-Host "DocFX version $release_version downloaded successfully" $fail = $false Break } catch { Write-Host "Downloading DocFX version $release_version failed, trying next ($tries / 3)" #Return 1 } } - + # Check if we succedded in downloading if ($fail) { Return 1 } - + # Switch directory Set-Location -Path "$target_dir" - + # Extract the release try { Write-Host "Extracting DocFX" Expand-Archive -path "$target_path" -destinationpath "$target_dir" } - catch + catch { Return 1 } - + # Remove the downloaded zip Write-Host "Removing temporary files" Remove-Item "$target_path" - + # Add DocFX to PATH Write-Host "Adding DocFX to PATH" if ($Env:OS -eq $null) { $Env:DOCFX_PATH = "$target_dir" } - else + else { $Env:PATH = "$target_dir;$current_path" } Set-Location -path "$current_location" - + Return 0 } # Downloads and installs latest version of 7-zip CLI function Install-7zip([string] $target_dir_path) { # First, download 7-zip 9.20 CLI to extract latest CLI # http://www.7-zip.org/a/7za920.zip - + Write-Host "Installing 7-zip" # Check if the target directory exists # If it does, remove it if (Test-Path "$target_dir_path") { Write-Host "Target directory exists, deleting" Remove-Item -recurse -force "$target_dir_path" } # Create target directory $target_dir = New-Item -type directory "$target_dir_path" $target_fn = "7za920.zip" - + # Form target path $target_dir = $target_dir.FullName $target_path = Join-Path "$target_dir" "v920" $target_dir_920 = New-Item -type directory "$target_path" - + $target_dir_920 = $target_dir_920.FullName $target_path = Join-Path "$target_dir_920" "$target_fn" - + # Download the 9.20 CLI try { Write-Host "Downloading 7-zip 9.20 CLI to $target_path" Invoke-WebRequest -uri "http://www.7-zip.org/a/7za920.zip" -outfile "$target_path" Set-Location -Path "$target_dir_920" } catch { Return 1 } - + # Extract the 9.20 CLI try { Write-Host "Extracting 7-zip latest CLI" Expand-Archive -path "$target_path" -destinationpath "$target_dir_920" } - catch + catch { Return 1 } - + # Temporarily add the 9.20 CLI to PATH Write-Host "Adding 7-zip 9.20 CLI to PATH" $old_path = $Env:PATH $Env:PATH = "$target_dir_920;$old_path" - + # Next, download latest CLI # http://www.7-zip.org/a/7z1604-extra.7z - + # Form target path $target_version = "19.00" $target_fn = "7z1900-extra.7z" $target_path = Join-Path "$target_dir" "$target_fn" - + # Download the latest CLI try { Write-Host "Downloading 7-zip $target_version CLI to $target_path" Invoke-WebRequest -uri "http://www.7-zip.org/a/$target_fn" -outfile "$target_path" Set-Location -Path "$target_dir" } catch { Return 1 } - + # Extract the latest CLI Write-Host "Extracting 7-zip $target_version CLI" & 7za x "$target_path" | Out-Host if ($LastExitCode -ne 0) { Return $LastExitCode } - + # Remove the 9.20 CLI from PATH Write-Host "Removing 7-zip 9.20 CLI from PATH" $Env:PATH = "$old_path" - + # Remove temporary files and 9.20 CLI Write-Host "Removing temporary files" Remove-Item -recurse -force "$target_dir_920" Remove-Item -recurse -force "$target_path" - + # Add the latest CLI to PATH Write-Host "Adding 7-zip $target_version CLI to PATH" $target_dir = Join-Path "$target_dir" "x64" $Env:PATH = "$target_dir;$old_path" Set-Location -path "$current_location" - + Return 0 } # Builds the documentation using available DocFX function Build-Docs([string] $target_dir_path) { # Check if documentation source path exists if (-not (Test-Path "$target_dir_path")) { #Write-Host "Specified path does not exist" Return 65536 } - + # Check if documentation source path is a directory $target_path = Get-Item "$target_dir_path" if (-not ($target_path -is [System.IO.DirectoryInfo])) { #Write-Host "Specified path is not a directory" Return 65536 } - + # Form target path $target_path = $target_path.FullName - + # Form component paths $docs_site = Join-Path "$target_path" "_site" $docs_api = Join-Path "$target_path" "api" $docs_obj = Join-Path "$target_path" "obj" - + # Check if API documentation source path exists if (-not (Test-Path "$docs_api")) { #Write-Host "API build target directory does not exist" Return 32768 } - + # Check if API documentation source path is a directory $docs_api_dir = Get-Item "$docs_api" if (-not ($docs_api_dir -is [System.IO.DirectoryInfo])) { #Write-Host "API build target directory is not a directory" Return 32768 } - + # Purge old API documentation Write-Host "Purging old API documentation" Set-Location -path "$docs_api" Remove-Item "*.yml" Set-Location -path "$current_location" - + # Check if old built site exists # If it does, remove it if (Test-Path "$docs_site") { Write-Host "Purging old products" Remove-Item -recurse -force "$docs_site" } - + # Create target directory for the built site $docs_site = New-Item -type directory "$docs_site" $docs_site = $docs_site.FullName - + # Check if old object cache exists # If it does, remove it if (Test-Path "$docs_obj") { Write-Host "Purging object cache" Remove-Item -recurse -force "$docs_obj" } - + # Create target directory for the object cache $docs_obj = New-Item -type directory "$docs_obj" $docs_obj = $docs_obj.FullName - + # Enter the documentation directory Set-Location -path "$target_path" - + # Check OS # Null means non-Windows if ($Env:OS -eq $null) { # Generate new API documentation & mono "$Env:DOCFX_PATH/docfx.exe" docfx.json | Out-Host # Check if successful if ($LastExitCode -eq 0) { # Build new documentation site & mono "$Env:DOCFX_PATH/docfx.exe" build docfx.json | Out-Host } } - else + else { # Generate new API documentation & docfx docfx.json | Out-Host - + # Check if successful if ($LastExitCode -eq 0) { # Build new documentation site & docfx build docfx.json | Out-Host } } - + # Exit back Set-Location -path "$current_location" - + # Check if building was a success if ($LastExitCode -eq 0) { Return 0 } else { Return $LastExitCode } } # Packages the build site to a .tar.xz archive function Package-Docs([string] $target_dir_path, [string] $output_dir_path, [string] $pack_name) { # Form target path $target_path = Get-Item "$target_dir_path" $target_path = $target_path.FullName $target_path = Join-Path "$target_path" "_site" - + # Form output path $output_path_dir = Get-Item "$output_dir_path" $output_path_dir = $output_path_dir.FullName $output_path = Join-Path "$output_path_dir" "$pack_name" - + # Enter target path Set-Location -path "$target_path" - + # Check if target .tar exists # If it does, remove it if (Test-Path "$output_path.tar") { Write-Host "$output_path.tar exists, deleting" Remove-Item "$output_path.tar" } - + # Package .tar archive Write-Host "Packaging docs to $output_path.tar" & 7za -r a "$output_path.tar" * | Out-Host - + # Check if prepackaging was a success if ($LastExitCode -ne 0) { Return $LastExitCode } - + # Go to package's location Set-Location -path "$output_path_dir" - + # Check if target .tar.xz exists # If it does, remove it if (Test-Path "$output_path.tar.xz") { Write-Host "$output_path.tar.xz exists, deleting" Remove-Item "$output_path.tar.xz" } - + # Package .tar.xz Write-Host "Packaging docs to $output_path.tar.xz" & 7za -sdel -mx9 a "$pack_name.tar.xz" "$pack_name.tar" | Out-Host - + # Exit back Set-Location -path "$current_location" - + # Check if packaging was a success if ($LastExitCode -eq 0) { Return 0 } else { Return $LastExitCode } } # Install DocFX $result = Install-DocFX "$docfx_path" if ($result -ne 0) { Write-Host "Installing DocFX failed" Restore-Environment $host.SetShouldExit(1) Exit 1 } # Install 7-zip, if Windows if ($Env:OS -ne $null) { $result = Install-7zip "$sevenzip_path" if ($result -ne 0) { Write-Host "Installing 7-zip failed" Restore-Environment $host.SetShouldExit(1) Exit 1 } } # Build and package docs # At this point nothing should fail as everything is already set up $result = Build-Docs "$DocsPath" if ($result -eq 0) { $result = Package-Docs "$DocsPath" "$OutputPath" "$PackageName" if ($result -ne 0) { Write-Host "Packaging API documentation failed" } } else { Write-Host "Building API documentation failed" } # Restore the environment Restore-Environment # All was well, exit with success if ($result -eq 0) { Write-Host "All operations completed" Exit 0 } else { $host.SetShouldExit($result) Exit $result }