Merge pull request #40 from josh-green/master

Migrating documentation to DocFx.  This is an initial transformation of existing documentation, and will be the basis of further cleanup work (see Issue #41).

.gitignore

@@ -189,3 +189,6 @@ GeneratedArtifacts/
 _Pvt_Extensions/
 ModelManifest.xml
 /.vs/config
+Documentation/_site/
+Documentation/packages/
+.vs/

CoreLibraries.sln.DotSettings

@@ -213,6 +213,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</s:String>
 	<s:Boolean x:Key="/Default/Environment/SettingsMigration/IsMigratorApplied/=JetBrains_002EReSharper_002EPsi_002ECSharp_002ECodeStyle_002ESettingsUpgrade_002EMigrateBlankLinesAroundFieldToBlankLinesAroundProperty/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/Environment/SettingsMigration/IsMigratorApplied/=JetBrains_002EReSharper_002EPsi_002ECSharp_002ECodeStyle_002ESettingsUpgrade_002EMigrateThisQualifierSettings/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/Environment/SettingsMigration/IsMigratorApplied/=JetBrains_002EReSharper_002EPsi_002EJavaScript_002ECodeStyle_002ESettingsUpgrade_002EJsCodeFormatterSettingsUpgrader/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/Environment/SettingsMigration/IsMigratorApplied/=JetBrains_002EReSharper_002EPsi_002EJavaScript_002ECodeStyle_002ESettingsUpgrade_002EJsParsFormattingSettingsUpgrader/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/Environment/SettingsMigration/IsMigratorApplied/=JetBrains_002EReSharper_002EPsi_002EJavaScript_002ECodeStyle_002ESettingsUpgrade_002EJsWrapperSettingsUpgrader/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/Environment/UnitTesting/MsTestProvider/RunTestsEvenIfCodeCoverageEnabled/@EntryValue">True</s:Boolean>
 	<s:String x:Key="/Default/Environment/UserInterface/ShortcutSchemeName/@EntryValue">VS</s:String>

Documentation/articles/getting_started.md

@@ -0,0 +1,7 @@
+# Getting Started
+-----------------------------
+
+The topics in this section are intended to explain the setup and configuration to begin utilising **Core Libraries**.
+
+### Please select a sub-category:
+1. [Installation](installation.md)

Documentation/articles/installation.md

@@ -0,0 +1,3 @@
+# TODO: Installation
+------------------------------
+

Documentation/articles/service_client.md

@@ -0,0 +1 @@
+# TODO: Service Client

Documentation/articles/setting_up_performance_counters.md

@@ -0,0 +1 @@
+# TODO: Setting up performance counters

Documentation/articles/toc.yml

@@ -0,0 +1,11 @@
+- name: Getting Started
+  href: getting_started.md
+  items:
+  - name: Installation
+    href: installation.md
+- name: Using the libraries
+  href: using_libraries.md
+- name: Service Client
+  href: service_client.md
+- name: Setting up Performance Counters
+  href: setting_up_performance_counters.md

Documentation/articles/using_libraries.md

@@ -0,0 +1 @@
+# TODO: Using Libraries

Documentation/buildDocs.ps1

@@ -0,0 +1,104 @@
+# Build Documentation Script:
+#   This can be run as a standalone. The doc build is driven by docfx.json.
+#   More info on that can be found at https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#3-docfxjson-format
+#
+# Build dependencies:
+#   Chocolatey
+#   - nuget.commandline
+#   - docfx
+#
+# These are checked for at build time, and if the Chocolatey packages are not present, it 
+# will attempt to install them.
+
+Write-Host '> Building documentation...'
+
+$_cd = $PSScriptRoot
+$docFxConfigPath = (Resolve-Path "$_cd\docfx.json").Path
+
+# Get the docfx config as an object
+$docFxJson = Get-Content $docFxConfigPath | Out-String | ConvertFrom-Json
+
+if (([string]::IsNullOrWhiteSpace($_cd)) -OR ([string]::IsNullOrWhiteSpace($docFxJson.build.dest))) {
+    Throw 'Path not specified for the docfx output destination. See docfx.json : build -> dest'
+}
+
+# Select and resolve the build destination for the documentation.
+$docOutPath = "$_cd\$($docFxJson.build.dest)"
+
+# Check Chocolatey is installed by invoking the exe
+if (-NOT (Get-Command "choco" -errorAction SilentlyContinue)) {
+    Throw @'
+Chocolatey not found. It can be downloaded by running the following:
+Invoke-WebRequest https://chocolatey.org/install.ps1 -UseBasicParsing | Invoke-Expression
+'@
+}
+
+try {
+    choco install nuget.commandline
+}
+catch {
+    # Not sure if this would throw, catch in case
+    $_.Exception.Message
+    Write-Host ''
+    Throw '> Install of NuGet.CLI package failed'
+}
+
+if ($LastExitCode -ne 0) {
+    # If it swallowed the error and just returned exitcode
+    Write-Host ''
+    Throw '> NuGet.CLI install failed'
+}
+
+if (-NOT (Test-Path "$_cd\packages.config")) {
+    Write-Host ''
+    Throw '> NuGet restore for DocFx failed. Unable to find packages.config'
+}
+
+try {
+    nuget restore "$_cd\packages.config" -outputdirectory "$_cd\packages" -noninteractive
+}
+catch {
+    # Not sure if this would throw, catch in case
+    $_.Exception.Message
+    Write-Host ''
+    Throw '> NuGet restore for DocFx failed'
+}
+
+if ($LastExitCode -ne 0) {
+    # If it swallowed the error and just returned exitcode
+    Write-Host ''
+    Throw '> NuGet restore for DocFx failed'
+}
+
+# Once we know Chocolatey is installed, try get docfx
+try {
+    choco install docfx
+}
+catch {
+    # Not sure if this would throw, catch in case
+    $_.Exception.Message
+    Write-Host ''
+    Throw '> Install of DocFx package failed'
+}
+
+if ($LastExitCode -ne 0) {
+    # If it swallowed the error and just returned exitcode
+    Write-Host ''
+    Throw '> DocFx install failed'
+}
+
+if (Test-Path "$docOutPath") {
+    # Clear existing documentation
+    Remove-Item "$docOutPath\*" -Recurse
+}
+
+# Finally confirmed all packages required to build docs
+docfx "$_cd\docfx.json"
+
+if ($LastExitCode -ne 0) {
+    Write-Host ''
+    Throw '> DocFx run failed'
+}
+
+# Resolve the output path
+$docOutPath = Resolve-Path $docOutPath

Documentation/contributing.md

@@ -0,0 +1,4 @@
+# Contributing
+
+We would like to encourage you to contribute to the repository. This should be as easy as possible for you but there are a few things to consider when contributing.
+For a full guide on contributing please see the [information on GitHub](https://github.com/webappsuk/CoreLibraries/blob/master/CONTRIBUTING.md).

Documentation/docfx.json

@@ -0,0 +1,71 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [
+            "**/**.csproj"
+          ],
+          "exclude": [
+            "**/bin/**",
+            "**/obj/**",
+            "**/*.Test.csproj"
+          ],
+          "cwd": "../"
+        }
+      ],
+      "dest": "obj/api",
+      "filter": "filterConfig.yml"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "**/*.yml"
+        ],
+        "cwd": "obj/api",
+        "dest": "api"
+      },
+      {
+        "files": [
+          "articles/**/*.{md,yml}",
+          "*.{md,yml}",
+          "toc.yml"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**",
+          "articles/images/**"
+        ]
+      }
+    ],
+    "xref": [
+      "./packages/msdn.4.5.2.0.1.0-alpha-1611021200/content/msdn.4.5.2.zip",
+      "./packages/msdn.4.5.2.0.1.0-alpha-1611021200/content/namespaces.4.5.2.zip",
+      "http://nodatime.org/1.3.x.xrefmap.yml"
+    ],
+    "overwrite" : "specs/*.md",
+    "dest": "_site",
+    "globalMetadata": {
+      "_appTitle": "Web Applications UK Core Libraries Documentation",
+      "_appFaviconPath": "images/favicon.ico",
+      "_appLogoPath": "images/logo.svg",
+      "_enableSearch": true,
+      "_disableContribution": false,
+      "_appFooter": "© Copyright 2017 <a href='http://www.webappuk.com'>Web Applications UK Ltd</a> Core Libraries documentation, ALL RIGHTS RESERVED"
+    },
+    "fileMetadata": {
+      "_disableBreadcrumb": {
+        "index.md": true
+      }
+    },
+    "template": [
+      "default",
+      "template"
+    ]
+  }
+}

Documentation/filterConfig.yml

@@ -0,0 +1,6 @@
+apiRules:
+- exclude:
+    hasAttribute:
+      uid: System.ComponentModel.EditorBrowsableAttribute
+      ctorArguments:
+      - System.ComponentModel.EditorBrowsableState.Never

Documentation/index.md

@@ -0,0 +1,19 @@
+# Web Applications UK - Core Libraries
+
+![Branding](images/UK Logo (Black).png)
+
+## Description
+
+This library contains a treasure trove of utilities built up over a decade by Web Applications UK for simplifying the building and deployment of enterprise scale .NET solutions. The code has been successfully used, in various forms, for a number of years in production environments driving millions of transactions.
+
+As part of our ethos to have a positive impact on our wider community we are open sourcing them for everyone's benefit. We've also included the last three years of development history, showing how the utilities have evolved. Please let us know if you find the code useful in your own projects!
+
+We have carefully sanitised the code to protect our commercial customers interests, but if you do manage to spot any sensitive data please notify us directly using our support email.
+
+## Using the libraries
+
+All the code documented here is available on GitHub, and is also available, in compiled form, on nuget.org, as a collection of 10 inter-connected NuGets and can be installed into your .NET projects using NuGet. Alternatively, you can look for the individual NuGet files, or the compiled binaries in the releases.
+
+The official NuGets are strongly named and digitally signed by Web Applications UK, using a separate, secure process, that guarantees the NuGets authenticity. Although you can build your own NuGets from the source included here, the ability to upload them to nuget.org is not provided to protect casual users. If you wish to use a customised version of a library prior to a formal release, we recommend building and including the dll directly (but remember to include the License!).
+
+We will accept relevant pull requests, and issues, so please consider contributing.

Documentation/license.md

@@ -0,0 +1,30 @@
+# Licensing
+
+**Copyright © 2017, Web Applications UK Ltd**, _All rights
+reserved._
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the
+distribution.
+*Neither the name of Web Applications UK Ltd nor the names of its
+contributors may be used to endorse or promote products derived from this
+software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WEB APPLICATIONS UK LTD BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.

Documentation/packages.config

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<packages>
+  <package id="msdn.4.5.2" version="0.1.0-alpha-1611021200" targetFramework="net452" />
+</packages>

Documentation/specs/utilities.md

@@ -0,0 +1,53 @@
+---
+uid: WebApplications.Utilities
+---
+
+The [WebApplications.Utilities NuGet](https://www.nuget.org/packages/WebApplications.Utilities) contains the core utilities and is used by all the other specialized libraries.
+
+---
+uid: WebApplications.Utilities.Performance
+---
+
+The [WebApplications.Utilities.Performance NuGet](https://www.nuget.org/packages/WebApplications.Utilities.Performance) makes it easy to access to instance based performance counters and timers, includes the ability to [set up performance counters automatically as part of deployments](../articles/setting_up_performance_counters.md) (using the included [PerfSetup](../articles/setting_up_performance_counters.md) tool), or allows performance data to be collected in the absence of performance counters.
+
+---
+uid: WebApplications.Utilities.Logging
+---
+
+The [WebApplications.Utilities.Logging NuGet](https://www.nuget.org/packages/WebApplications.Utilities.Logging) provides powerful and exstinsible logging functionality, with effective translation and resource services.
+
+---
+uid: WebApplications.Utilities.Database
+---
+
+The [WebApplications.Utilities.Database NuGet](https://www.nuget.org/packages/WebApplications.Utilities.Database) is used for connecting enterprise level .Net applications to SQL Server databases, and allows for easy interaction with stored procedures, load balancing and concurrency control.  It also ensures that deployed schemas are valid based on the required usage.
+
+---
+uid: WebApplications.Utilities.Scheduling
+---
+
+The [WebApplications.Utilities.Scheduling NuGet](https://www.nuget.org/packages/WebApplications.Utilities.Scheduling) provides powerful routines for scheduling [Tasks](xref:System.Threading.Tasks) to run.
+
+---
+uid: WebApplications.Utilities.Service
+---
+
+The [WebApplications.Utilities.Service NuGet](https://www.nuget.org/packages/WebApplications.Utilities.Service) allows for the rapid creation of Windows Services.  Deployed services support the ability to install/uninstall themselves and can communicate with [custom clients](../articles/service_client.md) whilst running.
+
+---
+uid: WebApplications.Utilities.Cryptography
+---
+
+The [WebApplications.Utilities.Cryptography NuGet](https://www.nuget.org/packages/WebApplications.Utilities.Cryptography) provides utilities for easier use and configuration of cryptographic services in enterprise solutions.
+
+---
+uid: WebApplications.Utilities.Serialization
+---
+
+The [WebApplications.Utilities.Serialization NuGet](https://www.nuget.org/packages/WebApplications.Utilities.Serialization) provides serialization tools for .NET.
+
+---
+uid: WebApplications.Utilities.Initializer
+---
+
+The [WebApplications.Utilities.Initializer NuGet](https://www.nuget.org/packages/WebApplications.Utilities.Initializer) makes it easy to use Module Initialization logic in none-VB.NET libraries.  It works using IL rewriting.

Documentation/template/partials/affix.tmpl.partial

@@ -0,0 +1,20 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+
+<div class="hidden-sm col-md-2" role="complementary">
+  <div class="sideaffix">
+    {{^_disableContribution}}
+    <div class="contribution">
+      <ul class="nav">
+        {{#sourceurl}}
+        <li>
+          <a href="{{sourceurl}}" class="contribution-link">{{__global.viewSource}}</a>
+        </li>
+        {{/sourceurl}}
+      </ul>
+    </div>
+    {{/_disableContribution}}
+    <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
+    <!-- <p><a class="back-to-top" href="#top">Back to top</a><p> -->
+    </nav>
+  </div>
+</div>