Add version notes to CLI docs and restore version replacement, #911

src/dotnet/tools/lucene-cli/docs/index.md

@@ -8,14 +8,31 @@ The Lucene.NET command line interface (CLI) is a new cross-platform toolchain wi
 
 ## Installation
 
-Perform a one-time install of the lucene-cli tool using the following dotnet CLI command:
+Perform a one-time install of the lucene-cli tool using the [dotnet tool install](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-install) command,
+which will install the specified version:
 
 ```console
-dotnet tool install lucene-cli -g --prerelease
+dotnet tool install lucene-cli -g --version 4.8.0-beta00016
 ```
 
+<!--
+Note for source readers: The version argument above is updated by the
+docs.ps1 script when the docs are built, and this file should have that change
+committed when a new version of the CLI is released. This is to help strike
+a balance between having a real version number in this file for readers of
+the source and not having to manually update the version number in the docs
+every time a new version is released. You should still consult the NOTE
+below to ensure the version number is correct for the version of Lucene.NET
+you are using.
+-->
+
 > [!NOTE]
 > The version of the CLI you install should match the version of Lucene.NET you use.
+> The version can be specified using the [`--version` option](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-install#options)
+> of the [`dotnet tool install`](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-install) command.
+> For a list of available versions, see the [versions tab of the lucene-cli NuGet package](https://www.nuget.org/packages/lucene-cli#versions-body-tab)
+> or run the [dotnet tool list](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-list)
+> command using the package id `lucene-cli`.
 
 You may then use the lucene-cli tool to analyze and update Lucene.NET indexes and use its demos.
 
@@ -44,4 +61,3 @@ CLI command structure consists of the driver ("lucene"), the command, and possib
 lucene index check C:\my-index --verbose
 lucene index fix C:\my-index
 ```
-

websites/apidocs/docs.ps1

@@ -122,17 +122,9 @@ $DocFxGlobalJson = Join-Path -Path $ApiDocsFolder "docfx.global.json"
 $DocFxJsonContent = Get-Content $DocFxGlobalJson | ConvertFrom-Json
 $DocFxJsonContent._appFooter = "Copyright &copy; $((Get-Date).Year) The Apache Software Foundation, Licensed under the <a href='http://www.apache.org/licenses/LICENSE-2.0' target='_blank'>Apache License, Version 2.0</a><br/> <small>Apache Lucene.Net, Lucene.Net, Apache, the Apache feather logo, and the Apache Lucene.Net project logo are trademarks of The Apache Software Foundation. <br/>All other marks mentioned may be trademarks or registered trademarks of their respective owners.</small>"
 $DocFxJsonContent._appTitle = "Apache Lucene.NET $LuceneNetVersion Documentation"
-#$DocFxJsonContent._gitContribute.branch = "docs/$LuceneNetVersion"
-#$DocFxJsonContent._gitContribute.tag = "$VCSLabel"
 $DocFxJsonContent._luceneNetRel = $BaseUrl + "/"
 $DocFxJsonContent | ConvertTo-Json -depth 100 | Set-Content $DocFxGlobalJson
 
-# update the docfx.json file
-#$DocFxJson = Join-Path -Path $ApiDocsFolder "docfx.json"
-#$DocFxJsonContent = Get-Content $DocFxJson | ConvertFrom-Json
-#$DocFxJsonContent.build.globalMetadata._gitContribute.branch = "docs/$LuceneNetVersion"
-#$DocFxJsonContent.build.globalMetadata._gitContribute.tag = "$VCSLabel"
-
 # NOTE: The order of these depends on if one of the projects requries the xref map of another, normally all require the core xref map
 $DocFxJsonMeta = @(
     "docfx.core.json",
@@ -178,6 +170,12 @@ if ($? -and $DisableMetaData -eq $false) {
 }
 
 if ($? -and $DisableBuild -eq $false) {
+    # Update the lucene-cli docs `--version` argument to match the current version.
+    # This is to strike a balance between having the file have a real version number in source control
+    # and not having to remember to update the version in that file every time we release.
+    # Do not commit this change to the file unless you are doing a real version release.
+    (Get-Content -Path $CliIndexPath -Raw) -Replace '(?<=--version\s)\d+?\.\d+?\.\d+?(?:\.\d+?)?(?:-\w+)?', $LuceneNetVersion | Set-Content -Path $CliIndexPath
+
     # Update our TOC to the latest LuceneNetVersion
     (Get-Content -Path $TocPath1 -Raw) -Replace '(?<=lucenenet\.apache\.org\/docs\/)\d+?\.\d+?\.\d+?(?:\.\d+?)?(?:-\w+)?', $LuceneNetVersion | Set-Content -Path $TocPath1
     (Get-Content -Path $TocPath2 -Raw) -Replace '(?<=lucenenet\.apache\.org\/docs\/)\d+?\.\d+?\.\d+?(?:\.\d+?)?(?:-\w+)?', $LuceneNetVersion | Set-Content -Path $TocPath2