Merge pull request #1139 from dotnet/docs

Migrate all docs to docfx

Author: AArnott

README.md

@@ -22,121 +22,7 @@ What sets this package apart from other git-based versioning projects is:
 4. The computed version information is based on an author-defined major.minor version and an optional unstable tag, plus a shortened git commit ID.
 5. This project is supported by the [.NET Foundation](https://dotnetfoundation.org).
 
-## Installation and Configuration
-
-You can install Nerdbank.GitVersioning into your projects via NuGet or NPM.
-
-* Use the [nbgv .NET Core CLI tool](doc/nbgv-cli.md) (recommended)
-* [NuGet installation instructions](doc/nuget-acquisition.md)
-* [NPM installation instructions](doc/npm-acquisition.md)
-* [Cake Build installation instructions](doc/cake.md)
-
-You must also create [a version.json file](doc/versionJson.md) in your repo. See [migration notes](doc/migrating.md) if your repo already has a version.txt or version.json file from using another system.
-
-## How to leverage version stamping and runtime information
-
-See relevant documentation for any of these topics:
-
-* [.NET](doc/dotnet.md)
-* [Node](doc/node.md)
-* [VSIX](doc/vsix.md)
-* [NuProj](doc/nuproj.md)
-
-## Build
-
-We have docs to describe how to build with Nerdbank.GitVersioning
-for these build systems:
-
-* [MSBuild](doc/msbuild.md)
-* [gulp](doc/gulp.md)
-* [DNX](doc/dotnet-cli.md)
-* [dotnet CLI](doc/dotnet-cli.md)
-* [Cake Build](doc/cake.md)
-
-Also some special [cloud build considerations](doc/cloudbuild.md) (e.g. Azure Pipelines, GitHub Actions, etc.).
-
-## Where and how versions are calculated and applied
-
-This package calculates the version based on a combination of the version.json file,
-the git 'height' of the version, and the git commit ID.
-The height can optionally be incremented only for those [commits that change certain paths](doc/pathFilters.md).
-
-### Version generation
-
-Given the same settings as used in the discussion above, a NuGet or NPM package may be
-assigned this version:
-
-    1.0.24-alpha-g9a7eb6c819
-
-When built as a public release, the git commit ID is dropped:
-
-    1.0.24-alpha
-
-Learn more about [public releases versus prereleases](doc/public_vs_stable.md).
-
-## Frequently asked questions
-
-### What is 'git height'?
-
-Git 'height' is the number of commits in the longest path from HEAD (the code you're building)
-to some origin point, inclusive. In this case the origin is the commit that set the major.minor
-version number to the values found in HEAD.
-
-For example, if the version specified at HEAD is 3.4 and the longest path in git history from HEAD
-to where the version file was changed to 3.4 includes 15 commits, then the git height is "15".
-Another example is when HEAD points directly at the commit that changed the major.minor version,
-which has a git height of 1. [Learn more about 1 being the minimum revision number][GitHeightMinimum].
-
-### Why is the git height used for the PATCH version component for public releases?
-
-The git commit ID does not represent an alphanumerically sortable identifier
-in semver, and thus delivers a poor package update experience for NuGet package
-consumers. Incrementing the PATCH with each public release ensures that users
-who want to update to your latest NuGet package will reliably get the latest
-version.
-
-The git height is guaranteed to always increase with each release within a given major.minor version,
-assuming that each release builds on a previous release. And the height automatically resets when
-the major or minor version numbers are incremented, which is also typically what you want.
-
-### Why isn't the git commit ID included for public releases?
-
-It could be, but the git height serves as a pseudo-identifier already and the
-git commit id would just make it harder for users to type in the version
-number if they ever had to.
-
-Note that the git commit ID is *always* included in the
-`AssemblyInformationalVersionAttribute` so one can always match a binary to the
-exact version of source code that produced it.
-
-Learn more about [public releases and the git commit ID suffix](doc/public_vs_stable.md).
-
-### How do I translate from a version to a git commit and vice versa?
-
-While Nerdbank.GitVersioning calculates the version and applies it to most builds automatically,
-there can be occasions where you want to do so yourself or reverse the process to determine
-the commit that produced a given version.
-
-To do this use [the `nbgv` tool](doc/nbgv-cli.md) with the `get-version` or `get-commits` command.
-
-Another (deprecated) option is to use a pair of Powershell scripts are included in the Nerdbank.GitVersioning NuGet package
-that can help you to translate between the two representations.
-
-    tools\Get-CommitId.ps1
-    tools\Get-Version.ps1
-
-`Get-CommitId.ps1` takes a version and print out the matching commit (or possible commits, in the exceptionally rare event of a collision).
-`Get-Version.ps1` prints out the version information for the git commit current at HEAD.
-
-### How do I build Nerdbank.GitVersioning from source?
-
-Prerequisites and build instructions are found in our
-[contributing guidelines](CONTRIBUTING.md).
-
-### How do I consume the latest changes prior to their release on nuget.org?
-
-We have [a public feed][PublicCI] where our CI pushes packages.
-Adding the feed source URL to your nuget.config file will allow you to consume package versions that haven't been publicly released to nuget.org yet.
+Check out our [getting started documentation](https://dotnet.github.io/Nerdbank.GitVersioning/docs/getting-started.html).
 
 ## Code of Conduct
 
@@ -145,4 +31,3 @@ For more information see the [.NET Foundation Code of Conduct](https://dotnetfou
 
  [semver]: http://semver.org
  [GitHeightMinimum]: https://github.com/dotnet/Nerdbank.GitVersioning/issues/102#issuecomment-269591960
- [PublicCI]: https://dev.azure.com/andrewarnott/OSS/_packaging?_a=feed&feed=PublicCI

azure-pipelines/build.yml

@@ -48,6 +48,8 @@ jobs:
     displayName: 💅 Verify formatted code
     env:
       dotnetformat: true # part of a workaround for https://github.com/dotnet/sdk/issues/44951
+  - script: dotnet docfx docfx/docfx.json --warningsAsErrors --disableGitFeatures
+    displayName: 📚 Verify docfx build
 
 - job: WrapUp
   dependsOn:

doc/dotnet-cli.md

@@ -1,17 +1,4 @@
 {
-	"metadata": [
-		{
-			"src": [
-				{
-					"src": "../src/Library",
-					"files": [
-						"**/*.csproj"
-					]
-				}
-			],
-			"dest": "api"
-		}
-	],
 	"build": {
 		"content": [
 			{
@@ -39,8 +26,8 @@
 			"modern"
 		],
 		"globalMetadata": {
-			"_appName": "Library",
-			"_appTitle": "Library",
+			"_appName": "Nerdbank.GitVersioning",
+			"_appTitle": "Nerdbank.GitVersioning",
 			"_enableSearch": true,
 			"pdf": false
 		}

doc/nuproj.md

@@ -1,4 +1,4 @@
-# MSBuild
+# MSBuild / `dotnet build`
 
 Installing the `Nerdbank.GitVersioning` package from NuGet into your MSBuild-based projects is the recommended way to add version information to your MSBuild project outputs including assemblies, native dll's, and packages.
 
@@ -168,7 +168,7 @@ If you still see many invocations, you may have a build that sets global propert
 Investigate this using the MSBuild `/bl` switch and view the log with the excellent [MSBuild Structured Log Viewer](https://msbuildlog.com) tool.
 Using that tool, search for `$task GetBuildVersion` and look at the global properties passed to the special `Nerdbank.GitVersioning.Inner.targets` project, as shown:
 
-[![MSBuild Structure Logger screenshot](globalproperties_log.png)
+[![MSBuild Structure Logger screenshot](../../images/globalproperties_log.png)
 
 Compare the set of global properties for each `Nerdbank.GitVersioning.Inner.targets` project to identify which properties are unique each time.
 Add the names of the unique properties to the `Directory.Build.props` file:

docfx/docfx.json

@@ -1,18 +1,50 @@
-# .NET support
+# .NET
 
-Nerdbank.GitVersioning offers first class version stamping support for .NET assemblies.
+Nerdbank.GitVersioning offers first class version stamping support for .NET assemblies and NuGet packages.
+
+## Hello, World! for versioning
+
+The following commands demonstrate Nerdbank.GitVersioning on a new project:
+
+```ps1
+mkdir NbgvExample
+cd NbgvExample
+git init
+dotnet new classlib --framework=netstandard2.0
+git add *.cs *.csproj
+git commit -m "Plain vanilla project"
+dotnet tool install -g nbgv
+nbgv install
+git commit -m "Add version stamping"
+dotnet pack
+dir .\bin\Release\*.nupkg
+```
+
+This will build a package versioned 1.0.1-beta.
+
+Then make a small change, commit the change, and pack again to see the version change:
+
+```ps1
+touch README.md
+git add README.md
+git commit -m "Add README"
+dotnet pack
+dir .\bin\Release\*.nupkg
+```
+
+Now we have another package, the new one versioned 1.0.2-beta.
 
 ## Assembly version generation
 
-During the build it adds source code such as this to your compilation:
+During the build Nerdbank.GitVersioning adds source code such as this to your compilation:
 
 ```csharp
 [assembly: System.Reflection.AssemblyVersion("1.0")]
 [assembly: System.Reflection.AssemblyFileVersion("1.0.24.15136")]
 [assembly: System.Reflection.AssemblyInformationalVersion("1.0.24-alpha+g9a7eb6c819")]
 ```
 
-* The first and second integer components of the versions above come from the 
+* The first and second integer components of the versions above come from the
 version file.
 * The third integer component of the version here is the height of your git history up to
 that point, such that it reliably increases with each release.

doc/cake.md renamed to docfx/docs/build-systems/cake.md

@@ -1,8 +1,6 @@
-# Node support
+# Node.js
 
-## Acquisition
-
-See [NPM acquisition](npm-acquisition.md).
+First, you should [acquire the `nerdbank-gitversioning` NPM package](../npm-acquisition.md).
 
 ## Acquiring version information
 
@@ -28,4 +26,4 @@ Will print out a JavaScript object resembling this:
 
 ## Build integration
 
-Check out our [instructions for gulp](gulp.md).
+Check out our [instructions for gulp](../build-systems/gulp.md).

doc/gulp.md renamed to docfx/docs/build-systems/gulp.md

@@ -1,11 +1,11 @@
-# VSIX support
+# VSIX projects
 
 Nerdbank.GitVersioning can automatically stamp the VSIXs you build with
-the version calculated from your version.json file and git height. 
+the version calculated from your version.json file and git height.
 
 ## Installation
 
-1. Install the Nerdbank.GitVersioning NuGet package into your VSIX-generating project.
+1. [Install the Nerdbank.GitVersioning NuGet package](../nuget-acquisition.md) into your VSIX-generating project.
 1. Open the `source.extension.vsixmanifest` file in a code editor
 and set the `PackageManifest/Metadata/Identity/@Version` attribute to this
 value: `|%CurrentProject%;GetBuildVersion|`

doc/msbuild.md renamed to docfx/docs/build-systems/msbuild.md

@@ -0,0 +1,65 @@
+# Frequently asked questions
+
+## What is 'git height'?
+
+Git 'height' is the number of commits in the longest path from HEAD (the code you're building)
+to some origin point, inclusive. In this case the origin is the commit that set the major.minor
+version number to the values found in HEAD.
+
+For example, if the version specified at HEAD is 3.4 and the longest path in git history from HEAD
+to where the version file was changed to 3.4 includes 15 commits, then the git height is "15".
+Another example is when HEAD points directly at the commit that changed the major.minor version,
+which has a git height of 1. [Learn more about 1 being the minimum revision number][GitHeightMinimum].
+
+## Why is the git height used for the PATCH version component for public releases?
+
+The git commit ID does not represent an alphanumerically sortable identifier
+in semver, and thus delivers a poor package update experience for NuGet package
+consumers. Incrementing the PATCH with each public release ensures that users
+who want to update to your latest NuGet package will reliably get the latest
+version.
+
+The git height is guaranteed to always increase with each release within a given major.minor version,
+assuming that each release builds on a previous release. And the height automatically resets when
+the major or minor version numbers are incremented, which is also typically what you want.
+
+## Why isn't the git commit ID included for public releases?
+
+It could be, but the git height serves as a pseudo-identifier already and the
+git commit id would just make it harder for users to type in the version
+number if they ever had to.
+
+Note that the git commit ID is *always* included in the
+`AssemblyInformationalVersionAttribute` so one can always match a binary to the
+exact version of source code that produced it.
+
+Learn more about [public releases and the git commit ID suffix](public-vs-stable.md).
+
+## How do I translate from a version to a git commit and vice versa?
+
+While Nerdbank.GitVersioning calculates the version and applies it to most builds automatically,
+there can be occasions where you want to do so yourself or reverse the process to determine
+the commit that produced a given version.
+
+To do this use [the `nbgv` tool](nbgv-cli.md) with the `get-version` or `get-commits` command.
+
+Another (deprecated) option is to use a pair of Powershell scripts are included in the Nerdbank.GitVersioning NuGet package
+that can help you to translate between the two representations.
+
+    tools\Get-CommitId.ps1
+    tools\Get-Version.ps1
+
+`Get-CommitId.ps1` takes a version and print out the matching commit (or possible commits, in the exceptionally rare event of a collision).
+`Get-Version.ps1` prints out the version information for the git commit current at HEAD.
+
+## How do I build Nerdbank.GitVersioning from source?
+
+Prerequisites and build instructions are found in our
+[contributing guidelines](https://github.com/dotnet/Nerdbank.GitVersioning/tree/main/CONTRIBUTING.md).
+
+## How do I consume the latest changes prior to their release on nuget.org?
+
+We have [a public feed][PublicCI] where our CI pushes packages.
+Adding the feed source URL to your nuget.config file will allow you to consume package versions that haven't been publicly released to nuget.org yet.
+
+[PublicCI]: https://dev.azure.com/andrewarnott/OSS/_packaging?_a=feed&feed=PublicCI