Docs customised home page (#892)

* customized documentation home page

* fix typo

* remove whitespace

* Spelling fixes

* Updated script and notes for running locally

* doc home page upgrade

* revert commented out lines in buildscript

* Various tweaks and improvements

* review

Co-authored-by: Bart Koelman <bart@degreed.com>

Author: maurei

appveyor.yml

@@ -35,6 +35,9 @@ after_build:
             git clone https://github.com/json-api-dotnet/JsonApiDotNetCore.git -b gh-pages origin_site -q
             Copy-Item origin_site/.git _site -recurse
             Copy-Item CNAME _site/CNAME
+            Copy-Item home/index.html _site/index.html
+            Copy-Item home/favicon.icon _site/favicon.icon
+            Copy-Item home/assets/* _site/styles/ -Recurse
             CD _site
             git add -A 2>&1
             git commit -m "CI Updates" -q

docs/README.md

@@ -1,6 +1,18 @@
-# Running
+# Intro
+Documentation for JsonApiDotNetCore is produced using [DocFX](https://dotnet.github.io/docfx/) from several files in this directory.
+In addition, the example request/response pairs are generated by executing `curl` commands against the GettingStarted project.
 
+# Installation
+Run the following commands once to setup your system:
+```
+choco install docfx -y
+```
+```
+npm install -g httpserver
+```
+
+# Running
+The next command regenerates the documentation website and opens it in your default browser:
 ```
-./generate.sh
-docfx ./docfx.json --serve
+pwsh ./build-dev.ps1
 ```

docs/build-dev.ps1

@@ -0,0 +1,22 @@
+# This script assumes that you have already installed docfx and httpserver.
+# If that's not the case, run the next commands:
+#   choco install docfx -y
+#   npm install -g httpserver
+
+Remove-Item _site -Recurse -ErrorAction Ignore
+
+dotnet build .. --configuration Release
+Invoke-Expression ./generate-examples.ps1
+
+docfx ./docfx.json
+Copy-Item home/index.html _site/index.html
+Copy-Item home/favicon.ico _site/favicon.ico
+Copy-Item -Recurse home/assets/* _site/styles/
+
+cd _site
+httpserver &
+Start-Process "http://localhost:8080/"
+
+Write-Host ""
+Write-Host "Web server started. Press Enter to close."
+$key = [Console]::ReadKey()

docs/docfx.json

@@ -16,11 +16,10 @@
     ],
     "build": {
         "content": [
-            {
-                "files": [ "api/**.yml", "api/index.md" ]
-            },
             {
                 "files": [
+                    "api/**.yml",
+                    "api/index.md",
                     "getting-started/**.md",
                     "getting-started/**/toc.yml",
                     "usage/**.md",