Merge pull request #3858 from asbjornu/feature/docker-docs

Docker documentation (v6)

Author: arturcic

build.ps1

@@ -1,4 +1,4 @@
-#!/usr/bin/pwsh
+#!/usr/bin/env pwsh
 <#
 .PARAMETER Stage
 The build stage to execute.

docs/input/docs/usage/docker.md

@@ -0,0 +1,27 @@
+---
+Order: 50
+Title: Docker
+Description: |
+    Use GitVersion through one of its many published Docker containers.
+---
+
+GitVersion can be used through one of its many published Docker
+containers. The list of available containers can be found on
+[Docker Hub][docker-hub]. Once you've found the image you want to use,
+you can run it like this:
+
+```shell
+docker run --rm --volume "$(pwd):/repo" gittools/gitversion:6.0.0-fedora.36-6.0 /repo
+```
+
+The above command will run GitVersion with the current directory
+mapped to `/repo` inside the container (the `--volume "$(pwd):/repo"`
+part). The `/repo` directory is then passed in as the argument
+GitVersion should use to calculate the version.
+
+The `--rm` flag will remove the container after it has finished
+running.
+
+[Explore GitVersion on Docker Hub][docker-hub]{.btn .btn-primary}
+
+[docker-hub]: https://hub.docker.com/r/gittools/gitversion

docs/input/docs/usage/library.md

@@ -15,9 +15,9 @@ patch releases, it's a useful option to some.
 
 :::{.alert .alert-warning}
 **Warning**
-
-We are not semantically versioning this library and it should be considered
-unstable.
+The library API is not stable and does not follow the semantic versioning
+of the GitVersion tool. A patch release of the tool may break the library
+and we will refactor and change the library API without notice.
 :::
 
 <a href="/api" class="btn btn-primary">Explore the GitVersion library API</a>

docs/readme.md

@@ -17,28 +17,35 @@ expected.
 
 ## Serving the documentation locally
 
-To serve up the documentation locally, you need to run the script
+To serve up the documentation locally, you need to run the following
+commands:
 
 ```shell
+./build.ps1 -Stage build -Target PrepareBuild
+./build.ps1 -Stage build -Target Build
 ./build.ps1 -Stage docs -Target PreviewDocs
 ```
 
 ### On Windows
 
-On Windows, you need to run the following build command in a PowerShell
+On Windows, you need to run the following commands in a PowerShell
 terminal:
 
 ```shell
+./build.ps1 -Stage build -Target PrepareBuild
+./build.ps1 -Stage build -Target Build
 ./build.ps1 -Stage docs -Target PreviewDocs
 ```
 
 ### On Unix
 
 First you need to [install PowerShell on macOS][ps-mac] or [Linux][ps-linux],
-then execute the following command:
+then execute the following commands:
 
 ```shell
-pwsh ./build.ps1 -Stage docs -Target PreviewDocs
+./build.ps1 -Stage build -Target PrepareBuild
+./build.ps1 -Stage build -Target Build
+./build.ps1 -Stage docs -Target PreviewDocs
 ```
 
 After pressing enter, the documentation will be generated and then served under