Improved NuGet package creation docs. (#19196)

* Added NuGet package creation docs.

Moved the information about creating local NuGet packages from the general build instructions into its own document, and tried to flesh out the information in there.

* Restore the link.

As suggested in PR review.

---------

Co-authored-by: Julien Lebosquain <[email protected]>

docs/build.md

@@ -97,25 +97,6 @@ On macOS it is necessary to build and manually install the respective native lib
 ./build.sh CompileNative
 ```
 
-# Building Avalonia into a local NuGet cache
-
-It is possible to build Avalonia locally and generate NuGet packages that can be used locally to test local changes.
-
-First, install Nuke's dotnet global tool like so:
-
-```bash
-dotnet tool install Nuke.GlobalTool --global
-```
-
-Then you need to run:
-```bash
-nuke --target BuildToNuGetCache --configuration Release
-```
-
-This command will generate nuget packages and push them into a local NuGet automatically.
-To use these packages use `9999.0.0-localbuild` package version. 
-Each time local changes are made to Avalonia, running this command again will replace old packages and reset cache for the same version.
-
 ## Browser
 
 To build and run browser/wasm projects, it's necessary to install NodeJS.
@@ -124,3 +105,7 @@ You can find latest LTS on https://nodejs.org/.
 ## Windows
 
 It is possible to run some .NET Framework samples and tests using .NET Framework SDK. You need to install at least 4.7 SDK.
+
+## Building Avalonia into a local NuGet cache
+
+See [Building Local NuGet Packages](nuget.md)

docs/index.md

@@ -12,6 +12,7 @@ This documentation covers Avalonia framework development. For user documentation
 
 - [Debugging the XAML Compiler](debug-xaml-compiler.md)
 - [Porting Code from 3rd Party Sources](porting-code-from-3rd-party-sources.md)
+- [Building Local NuGet Packages](nuget.md)
 
 ## Releases
 

docs/nuget.md

@@ -0,0 +1,56 @@
+# Building Local NuGet Packages
+
+To build NuGet packages, one can use the `CreateNugetPackages` target:
+
+Windows
+
+```
+.\build.ps1 CreateNugetPackages
+```
+
+Linux/macOS
+
+```
+./build.sh CreateNugetPackages
+```
+
+Or if you have Nuke's [dotnet global tool](https://nuke.build/docs/getting-started/installation/) installed:
+
+```
+nuke CreateNugetPackages
+```
+
+The produced NuGet packages will be placed in the `artifacts\nuget` directory.
+
+> [!NOTE]
+> The rest of this document will assume that you have the Nuke global tool installed, as the invocation is the same on all platforms. You can always replace `nuke` in the instructions below with the `build` script relvant to your platform.
+
+By default the packages will be built in debug configuration. To build in relase configuration add the `--configuration` parameter, e.g.:
+
+```
+nuke CreateNugetPackages --configuration Release
+```
+
+To configure the version of the built packages, add the `--force-nuget-version` parameter, e.g.:
+
+```
+nuke CreateNugetPackages --force-nuget-version 11.4.0
+```
+
+## Building to the Local Cache
+
+Building packages with the `CreateNugetPackages` target has a few gotchas:
+
+- One needs to set up a local nuget feed to consume the packages
+- When building on an operating system other than macOS, the Avalonia.Native package will not be built, resulting in a NuGet error when trying to use Avalonia.Desktop
+- It's easy to introduce versioning problems
+
+For these reasons, it is possible to build Avalonia directly to your machine's NuGet cache using the `BuildToNuGetCache` target:
+
+```bash
+nuke --target BuildToNuGetCache --configuration Release
+```
+
+This command will generate nuget packages and push them into your local NuGet cache (usually `~/.nuget/packages`) with a version of  `9999.0.0-localbuild`.
+
+Each time local changes are made to Avalonia, running this command again will replace the old packages and reset the cache, meaning that the changes should be picked up automatically by msbuild.