feat(docs): Build and deploy docs site (#77)

chore: doc corrections
chore: Add missing header
chore: Removed 'solution items'

.gitignore

@@ -4,4 +4,8 @@ packages
 bin
 obj
 integration/temp
+log.txt
+/build
+/docs/api/*.yml
+/docs/api/.manifest
 coverage.json

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "simpleversion"
+    ]
+}

Packages.props

@@ -9,7 +9,7 @@
     <PackageReference Update="LibGit2Sharp"                         Version="0.25.3" />
     <PackageReference Update="LibGit2Sharp.NativeBinaries"          Version="1.0.235" />
     <PackageReference Update="Newtonsoft.Json"                      Version="11.0.*" />
-    <PackageReference Update="Microsoft.Packaging.Tools.Trimming"   Version="1.1.0-*" PrivateAssets="All"/>
+    <PackageReference Update="Microsoft.Packaging.Tools.Trimming"   Version="1.1.0-*" PrivateAssets="All" />
   </ItemGroup>
 
   <ItemGroup Label="Test library packages">

README.md

@@ -1,85 +1,35 @@
-![Logo]
-
 SimpleVersion
 =============
 [![Nuget](https://img.shields.io/nuget/v/SimpleVersion.Core.svg?logo=nuget)][NugetRel]
 [![Nuget (with prereleases)](https://img.shields.io/nuget/vpre/SimpleVersion.Core.svg?logo=nuget)][NugetPre]
 [![Azure DevOps tests (branch)](https://img.shields.io/azure-devops/tests/Kieranties/SimpleVersion/1/master.svg?logo=azuredevops)][AzureRelease]
 [![License](https://img.shields.io/github/license/Kieranties/SimpleVersion.svg?logo=github)][License]
 
-Brief
------
-
 SimpleVersion aims to simplify how you version the artifacts of your git repository.
 
-Using SimpleVersion you can generate consistent, expected version numbers for
-each commit in your repository, based on a few simple configuration options.
-
-SimpleVersion uses some base configuration and the 'height' of your commit history
-to generate a version.  Height is calculated as the number of commits since your
-last change to the version.
-
-Future versions of SimpleVersion aim to provide:
-+ Validation of the version based on branch configuration
-+ Custom formatting configuration to support custom versioning schemes
-+ Git hooks to apply versioning changes based on commit messages
-+ and more!
-
-Why?
-----
-
-SimpleVersion borrows ideas from other excellent versioning tools, notably:
-[GitVersion] and [NerdBank.GitVersioning][NerdBank]. These tools also deliver
-the ability to version your repository based on the commits but work in a
-different manner:
-+ GitVersion relies heavily on branch names, merge messages and more. I have found this
-can sometimes cause issues without extreme management of best practices.
-+ Nerdbank is an excellent tool that removes many of the issues I ran into with
-GitVersion, however is more limited in scope for custom labelling formats.
-
 Usage
 -----
+Check out the [documentation site][docs] for guidance.
 
-To use SimpleVersion, you simply need to add a `.simpleversion.json` file to the
-root of your git repository and commit it.
-
-## Configuration
+Build
+-----
 
-```json
-{
-  "version": "0.1.0",
-  "label": [ "alpha2" ],
-  "branches": {
-    "release": [
-      "^refs/heads/master$",
-      "^refs/heads/preview/.+$",
-      "^refs/heads/release/.+$"
-    ]
-  }
-}
+To build SimpleVersion locally, run `build.ps1` from the root of the repository:
+```posh
+> .\build.ps1                       # => Runs a full build with unit tests
+> .\build.ps1 -BuildDocs            # => Runs a full build and creates the docs site
+> .\build.ps1 -BuildDocs -ServeDocs # Runs a full builds and serves the docs site
 ```
-The above configuration tells SimpleVersion that the version will be `0.1.0` and
-should have a release label of `alpha2`.  As their is a pre-release label, the
-height will be appended to label, generating a [Semver2] version `0.1.0-alpha2.3`
-if their were three commits since the version was last set.
-
-For further guidance, see the [configuration documentation][ConfigDoc] and the [usage documentation][UsageDoc].
-
-Resetting The Height
---------------------
 
-The height will be reset to 0 when SimpleVersion detects a change to either the
-`version` or the `label` in the `.simpleversion.json` file.
+Contributions
+-------------
 
-> You must commit changes to the file for SimpleVersion to identify the change
+Contributions, pull-requests, issues, and any other communications on the project
+are most welcome!  Please use one of the [issue templates] to get going.
 
-[logo]:         /docs/img/logo.png
-[semver2]:      https://semver.org/spec/v2.0.0.html
-[GitVersion]:   https://github.com/GitTools/GitVersion
-[NerdBank]:     https://github.com/aarnott/Nerdbank.GitVersioning
-[ConfigDoc]:    /docs/Configuration.md
-[UsageDoc]:     /docs/Usage.md
-[License]:      /LICENSE
-[NugetPre]:     https://www.nuget.org/packages?q=simpleversion
-[NugetRel]:     https://www.nuget.org/packages?q=simpleversion&prerel=false
-[AzureRelease]: https://dev.azure.com/Kieranties/SimpleVersion/_build?definitionId=1
+[NugetRel]:         https://www.nuget.org/packages?q=simpleversion&prerel=false
+[NugetPre]:         https://www.nuget.org/packages?q=simpleversion
+[AzureRelease]:     https://dev.azure.com/Kieranties/SimpleVersion/_build?definitionId=1
+[License]:          https://kieranties.mit-license.org/
+[Docs]:             https://simpleversion.kieranties.com
+[Issue Templates]:  https://github.com/Kieranties/SimpleVersion/issues/new/choose

SimpleVersion.sln

@@ -18,22 +18,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{9EEF54AE-E
 		test\Directory.Build.props = test\Directory.Build.props
 	EndProjectSection
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{0F190AA6-731C-425E-894B-F4A63A86200A}"
-	ProjectSection(SolutionItems) = preProject
-		.editorconfig = .editorconfig
-		.gitignore = .gitignore
-		.simpleversion.json = .simpleversion.json
-		azure-pipelines.yml = azure-pipelines.yml
-		Directory.Build.props = Directory.Build.props
-		Directory.Build.targets = Directory.Build.targets
-		global.json = global.json
-		LICENSE = LICENSE
-		localbuild.ps1 = localbuild.ps1
-		nuget.config = nuget.config
-		Packages.props = Packages.props
-		README.md = README.md
-	EndProjectSection
-EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SimpleVersion.Core", "src\SimpleVersion.Core\SimpleVersion.Core.csproj", "{C3908FD1-A959-4687-9221-C058698B126A}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SimpleVersion.Core.Tests", "test\SimpleVersion.Core.Tests\SimpleVersion.Core.Tests.csproj", "{C367CC5A-5ACC-442A-8885-ED9A94A9A43E}"
@@ -44,7 +28,6 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SimpleVersion.Cake", "src\S
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "shared", "shared", "{385532A7-26BE-4596-9EEE-E7C3984643ED}"
 	ProjectSection(SolutionItems) = preProject
-		shared\codecoverage.runsettings = shared\codecoverage.runsettings
 		shared\SimpleVersion.ruleset = shared\SimpleVersion.ruleset
 		shared\stylecop.json = shared\stylecop.json
 		shared\Tests.GlobalSuppressions.cs = shared\Tests.GlobalSuppressions.cs

build.ps1

@@ -8,7 +8,11 @@ param(
     [String]$RootPath = $PSScriptRoot,
     [String]$ArtifactsPath = (Join-Path $RootPath 'artifacts'),
     [String]$BuildPath = (Join-Path $RootPath 'build'),
-    [String]$PackagesPath = (Join-Path $RootPath 'packages')
+    [String]$DocsPath = (Join-Path $RootPath 'docs'),
+    [String]$PackagesPath = (Join-Path $RootPath 'packages'),
+    [Switch]$BuildDocs,
+    [Switch]$ServeDocs,
+    [String]$DocfxVersion = '2.42.0'
 )
 
 function exec([string]$cmd) {
@@ -32,6 +36,9 @@ if(!$Version) {
     $Version = '1.0.0-local'
     $env:Version = $Version
 }
+if($ServeDocs) {
+    $BuildDocs = $true
+}
 
 # Build/Pack
 Remove-Item $ArtifactsPath -Recurse -Force -ErrorAction Ignore
@@ -52,3 +59,23 @@ Get-ChildItem 'test' -Filter '*.csproj' -Recurse |
         )
         exec dotnet test $_.Fullname @testArgs
     }
+
+# docs
+if($BuildDocs) {
+    # Install docfx
+    $docfxRoot = "$BuildPath\docfx.console\$DocFxVersion"
+    $docfx = "$docfxRoot\tools\docfx.exe"
+    if(!(Test-Path $docfx)) {
+        $temp = (New-TemporaryFile).FullName + '.zip'
+        Invoke-WebRequest "https://www.nuget.org/api/v2/package/docfx.console/$DocFxVersion" -OutFile $temp
+        Expand-Archive $temp -DestinationPath $docfxRoot
+        Remove-Item $temp
+    }
+
+    $docfxArgs = @()
+    if($ServeDocs) {
+        $docfxArgs += '-s'
+    }
+    exec $docfx "$DocsPath\docfx.json" @docfxArgs
+    Copy-Item "$DocsPath\obj\site" -Recurse -Destination (Join-Path $ArtifactsPath 'docs') -Container
+}

docs/api/index.md

@@ -0,0 +1,2 @@
+# PLACEHOLDER
+TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!

docs/Configuration.md → docs/articles/configuration.md

@@ -9,7 +9,7 @@ Version
 
 The `Version` property allows you to specify the base version to be generated.
 You  may set the property with a version string that consists of one to four
-dot seperated digits.
+dot separated digits.
 
 All of the following are accepted values:
 ```json
@@ -41,23 +41,23 @@ in the final version.
 > Currently, only `Semver2` format supports `metadata`.
 
 ```json
-"MetaData" : []
-"MetaData" : ["demo"]
-"MetaData" : ["demo", "sprint1"]
+"Metadata" : []
+"Metadata" : ["demo"]
+"Metadata" : ["demo", "sprint1"]
 ```
 
-OffSet
+Offset
 ------
 
 Sometimes you may need to adjust the base value of the height. This could be
 when migrating from a previous versioning pattern, if a number of commits
 should be discounted, or any other reason.
 
-Specify the `OffSet` as a numeric value to impact the base value of the height.
+Specify the `Offset` as a numeric value to impact the base value of the height.
 
 ```json
-"OffSet" : -5
-"OffSet" : 4
+"Offset" : -5
+"Offset" : 4
 ```
 
 Branches
@@ -89,12 +89,51 @@ to the `Labels` property prefixed with `c` (for commit).
 
 In the above example, any branch called _master_, starting with _preview/_ or
 starting with _release/_ will **not** have the short sha appended. Generating a
-Semver2 verison of `0.1.0-alpha2.5` when there are five commits.
+Semver2 version of `0.1.0-alpha2.5` when there are five commits.
 
 All other branches will append the short sha, generating a Semver2 version of
 `0.1.0-alpha2.5.c903782` when there are five commits and the sha begins with
 _903782_
 
+### Overrides
+
+Overrides allow for certain elements of the version to be reconfigured based
+on the branch being built.  Overrides are matched by a regular expression where
+only the first match (if found) is used.
+
+```json
+{
+  "version": "0.2.0",
+  "label": [ "alpha1" ],
+  "branches": {
+    "release": [
+      "^refs/heads/master$",
+      "^refs/heads/preview/.+$",
+      "^refs/heads/release/.+$"
+    ],
+    "overrides": [
+      {
+        "match": "^refs/heads/feature/.+$",
+        "metadata": [ "{shortbranchname}" ]
+      },
+      {
+        "match": "^refs/heads/release/.+$",
+        "label": [],
+        "metadata": [ "*" ]
+      }
+    ]
+  }
+}
+```
+
+In th above example, any branch starting with _feature/_ will add the branches
+shortname as metadata to the generated version. E.g. _feature/testing_ will
+create a version of `0.2.0-alpha1.5.c903782+featuretesting` when there are five
+commits and the sha begins with _903782_
+
+Additionally, any branch beginning with _release/_ will strip the release label
+and have the height added into the metadata.
+
 Replacement Tokens
 ------------------
 
@@ -108,4 +147,4 @@ substitution of values during invocation.  The following tokens may be used:
 | Branch Name        | `{branchname}`       | `Label`, `Metadata`            | Inserts the canonical branch name, stripped of non-alphanumeric characters |
 | Short Branch Name  | `{shortbranchname}`  | `Label`, `Metadata`            | Inserts the friendly branch name, stripped of non-alphanumeric characters  |
 | Branch Name Suffix | `{branchnamesuffix}` | `Label`, `Metadata`            | Inserts the last segment of the canonical name of a branch				  |
-| Short Sha          | `{shortsha}`         | `Label`, `Metadata`            | Inserts the first seven characters of the commit sha, prefixed with `c`    |
+| Short Sha          | `{shortsha}`         | `Label`, `Metadata`            | Inserts the first seven characters of the commit sha, prefixed with `c`    |

docs/Usage.md → docs/articles/intro.md

@@ -1,10 +1,10 @@
-Usage
-=====
+Introduction
+============
 
 SimpleVersion is available as a command line tool (distributed via nuget), a Cake
 addin, or as a collection of libraries for direct consumption in a project.
 
-To get a better understanding of the values returnd from invoking SimpleVersion
+To get a better understanding of the values returned from invoking SimpleVersion
 see the [results documentation][results].
 
 Command Line Tool
@@ -18,6 +18,7 @@ You can install SimpleVersion.Command using `nuget.exe`:
 nuget install SimpleVersion.Command
 ```
 
+> [!INFO]
 > Execute `nuget install -?` for additional options
 
 Once downloaded, you can invoke SimpleVersion using the `exe` under the installed
@@ -74,4 +75,4 @@ RunTarget(target);
 ```
 
 
-[Results]: ./results.md
+[Results]: ./results.md

docs/Results.md → docs/articles/results.md

@@ -36,7 +36,7 @@ Properties
 | Patch | int | The Patch value reported in the Version string |
 | Revision | int | The Revision value. Always 0 even if not included in the Version string |
 | Height | int | The calculated height |
-| HeightPadded | int | The cacluated height padded to four digits |
+| HeightPadded | int | The calculated height padded to four digits |
 | Sha | string | The sha of the current commit at the time of invocation |
 | BranchName | string | The checked out branch at the time of invocation |
 | CanonicalBranchName | string | The full canonical name of the checked out branch at the time of invocation |
@@ -53,4 +53,4 @@ formats will be supported in a future version.
 | Semver2 | string | The full version string following the [Semver2] spec |
 
 [Semver1]: https://semver.org/spec/v1.0.0.html
-[Semver2]: https://semver.org/spec/v2.0.0.html
+[Semver2]: https://semver.org/spec/v2.0.0.html

docs/articles/toc.yml

@@ -0,0 +1,8 @@
+- name: Introduction
+  href: intro.md
+- name: Configuration
+  href: configuration.md
+- name: Results
+  href: results.md
+- name: Usage
+  href: usage.md