make.ps1

# Command file for Sphinx documentation

param (
 [string]$target="help"
)

Set-StrictMode-Version 3.0
$ErrorActionPreference="Stop"

$BUILDDIR="_build"
$SPHINXOPTS="--fail-on-warning --keep-going"
$_ALL_SPHINX_OPTS=$SPHINXOPTS

$_PYTHON=$Env:PYTHON??"py -3"
$_SPHINX_BUILD=$Env:SPHINXBUILD??".\venv\Scripts\sphinx-build"
$_SPHINX_LINT=$Env:SPHINXLINT??".\venv\Scripts\sphinx-lint"
$_VENV_DIR="venv"

functionNew-VirtualEnviromnent
{
Write-Host"Creating venv in $_VENV_DIR"
if (Get-Command"uv"-ErrorAction SilentlyContinue) {
& uv venv $_VENV_DIR
$Env:VIRTUAL_ENV=$_VENV_DIR
& uv pip install -r requirements.txt
Remove-Item Env:VIRTUAL_ENV
 } else {
&$_PYTHON-m venv venv
Write-Host"Installing requirements"
& venv\Scripts\python -m pip install -r requirements.txt
$Script:_PYTHON="venv\Scripts\python"
 }
}

functionInvoke-SphinxBuild
{
param (
 [string]$BuilderName,
 [string]$BuildDir,
 [string]$Options
 )
if (-Not (Test-Path-Path $_VENV_DIR)) { New-VirtualEnviromnent }
&$_SPHINX_BUILD-M $BuilderName"."$BuildDir$Options.Split("")
}

functionInvoke-Check {
if (-Not (Test-Path-Path $_VENV_DIR)) { New-VirtualEnviromnent }
&$_SPHINX_LINT-i tools -i venv --enable default-role
}

if ($target-Eq"help") {
Write-Host"Please use `make <target>` where <target> is one of"
Write-Host" venv to create a venv with necessary tools"
Write-Host" html to make standalone HTML files"
Write-Host" linkcheck to check all external links for integrity"
Write-Host" htmlview to open the index page built by the html target in your browser"
Write-Host" clean to remove the venv and build files"
Write-Host" check to check for stylistic and formal issues using sphinx-lint"
Write-Host" versions to update release cycle after changing release-cycle.json"
Exit
}

if ($target-Eq"clean") {
$ToClean=@(
$BUILDDIR,
$_VENV_DIR,
"include/branches.csv","include/end-of-life.csv",
"include/release-cycle.svg","include/release-cycle-all.svg"
 )
foreach ($itemin$ToClean) {
if (Test-Path-Path $item) {
Remove-Item-Path $item-Force -Recurse
 }
 }
Exit$LASTEXITCODE
}

if ($target-Eq"check") {
Invoke-Check
Exit$LASTEXITCODE
}

if ($target-Eq"versions") {
&$_PYTHON _tools/generate_release_cycle.py
if ($LASTEXITCODE-Ne0) { exit1 }
Write-Host"Release cycle data generated."
Exit$LASTEXITCODE
}

if ($target-Eq"htmlview") {
Invoke-SphinxBuild"html""$BUILDDIR""$_ALL_SPHINX_OPTS"
if (Test-Path-Path "$BUILDDIR\html\index.html") {
Write-Host"Opening $BUILDDIR\html\index.html in the default web browser..."
Start-Process"$BUILDDIR\html\index.html"
 }
Exit$LASTEXITCODE
}

Invoke-SphinxBuild"$target""$BUILDDIR""$_ALL_SPHINX_OPTS"
Exit$LASTEXITCODE