62 docs generation fsharp formatting

Content/Library/.config/dotnet-tools.json

@@ -25,6 +25,12 @@
       "commands": [
         "paket"
       ]
+    },
+    "fcswatch-cli": {
+      "version": "0.7.14",
+      "commands": [
+        "fcswatch"
+      ]
     }
   }
 }

Content/Library/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "workbench.colorCustomizations": {
+        "tab.unfocusedActiveBorder": "#fff0"
+    }
+}

Content/Library/MyLib.1.sln

@@ -1,4 +1,4 @@
-
+
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio 15
 VisualStudioVersion = 15.0.26124.0
@@ -11,6 +11,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{ACBEE43C
 EndProject
 Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "MyLib.1.Tests", "tests\MyLib.1.Tests\MyLib.1.Tests.fsproj", "{1CA2E092-2320-451D-A4F0-9ED7C7C528CA}"
 EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "docsTool", "docsTool\docsTool.fsproj", "{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -48,6 +50,18 @@ Global
 		{1CA2E092-2320-451D-A4F0-9ED7C7C528CA}.Release|x64.Build.0 = Release|x64
 		{1CA2E092-2320-451D-A4F0-9ED7C7C528CA}.Release|x86.ActiveCfg = Release|x86
 		{1CA2E092-2320-451D-A4F0-9ED7C7C528CA}.Release|x86.Build.0 = Release|x86
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Debug|x64.Build.0 = Debug|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Debug|x86.Build.0 = Debug|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Release|x64.ActiveCfg = Release|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Release|x64.Build.0 = Release|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Release|x86.ActiveCfg = Release|Any CPU
+		{8855EC73-F6A1-43D3-AFBC-04A3E09F9BD9}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{5D30E174-2538-47AC-8443-318C8C5DC2C9} = {C397A34C-84F1-49E7-AEBC-2F9F2B196216}

Content/Library/README.md

@@ -89,9 +89,10 @@ src/MyCoolNewLib/bin/
 - `GitRelease` - Creates a commit message with the [Release Notes](https://fake.build/apidocs/v5/fake-core-releasenotes.html) and a git tag via the version in the `Release Notes`.
 - `GitHubRelease` - Publishes a [GitHub Release](https://help.github.com/en/articles/creating-releases) with the Release Notes and any NuGet packages.
 - `FormatCode` - Runs [Fantomas](https://github.com/fsprojects/fantomas) on the solution file.
-- [`Release`](#Releasing) - Task that runs all release type tasks such as `PublishToNuGet` `GitRelease` and `GitHubRelease`. Make sure to read [Releasing](#Releasing) to setup your environment correctly for releases.
-
-
+- `BuildDocs` - Generates Documentation from `docsSrc` and the [XML Documentation Comments](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/) from your libraries in `src`.
+- `WatchDocs` - Generates documentation and starts a webserver locally.  It will rebuild and hot reload if it detects any changes made to `docsSrc` files, libraries in `src`, or the `docsTool` itself.
+- `ReleaseDocs` - Will stage, commit, and push docs generated in the `BuildDocs` target.
+- [`Release`](#Releasing) - Task that runs all release type tasks such as `PublishToNuGet`, `GitRelease`, `ReleaseDocs`, and `GitHubRelease`. Make sure to read [Releasing](#Releasing) to setup your environment correctly for releases.
 ---
 
 

Content/Library/build.fsx

@@ -1,4 +1,5 @@
 #load ".fake/build.fsx/intellisense.fsx"
+#load "docsTool/CLI.fs"
 #if !FAKE
 #r "Facades/netstandard"
 #r "netstandard"
@@ -17,6 +18,8 @@ open Fake.BuildServer
 open Fantomas
 open Fantomas.FakeHelpers
 
+
+
 BuildServer.install [
     AppVeyor.Installer
     Travis.Installer
@@ -65,14 +68,23 @@ let distGlob = distDir @@ "*.nupkg"
 let coverageThresholdPercent = 80
 let coverageReportDir =  __SOURCE_DIRECTORY__  @@ "docs" @@ "coverage"
 
+
+let docsDir = __SOURCE_DIRECTORY__  @@ "docs"
+let docsSrcDir = __SOURCE_DIRECTORY__  @@ "docsSrc"
+let docsToolDir = __SOURCE_DIRECTORY__ @@ "docsTool"
+
 let gitOwner = "MyGithubUsername"
 let gitRepoName = "MyLib.1"
 
+let gitHubRepoUrl = sprintf "https://github.com/%s/%s" gitOwner gitRepoName
+
 let releaseBranch = "master"
 let releaseNotes = Fake.Core.ReleaseNotes.load "RELEASE_NOTES.md"
 
 let publishUrl = "https://www.nuget.org"
 
+let docsSiteBaseUrl = sprintf "https://%s.github.io/%s" gitOwner gitRepoName
+
 let disableCodeCoverage = environVarAsBoolOrDefault "DISABLE_COVERAGE" false
 
 //-----------------------------------------------------------------------------
@@ -119,6 +131,9 @@ module dotnet =
     let watch cmdParam program args =
         DotNet.exec cmdParam (sprintf "watch %s" program) args
 
+    let run cmdParam args =
+        DotNet.exec cmdParam "run" args
+
     let tool optionConfig command args =
         DotNet.exec optionConfig (sprintf "%s" command) args
         |> failOnBadExitAndPrint
@@ -129,6 +144,49 @@ module dotnet =
     let sourcelink optionConfig args =
         tool optionConfig "sourcelink" args
 
+    let fcswatch optionConfig args =
+        tool optionConfig "fcswatch" args
+
+open DocsTool.CLIArgs
+module DocsTool =
+    open Argu
+    let buildparser = ArgumentParser.Create<BuildArgs>(programName = "docstool")
+    let buildCLI =
+        [
+            BuildArgs.SiteBaseUrl docsSiteBaseUrl
+            BuildArgs.ProjectGlob srcGlob
+            BuildArgs.DocsOutputDirectory docsDir
+            BuildArgs.DocsSourceDirectory docsSrcDir
+            BuildArgs.GitHubRepoUrl gitHubRepoUrl
+            BuildArgs.ProjectName gitRepoName
+            BuildArgs.ReleaseVersion releaseNotes.NugetVersion
+        ]
+        |> buildparser.PrintCommandLineArgumentsFlat
+
+    let build () =
+        dotnet.run (fun args ->
+            { args with WorkingDirectory = docsToolDir }
+        ) (sprintf " -- build %s" (buildCLI))
+        |> failOnBadExitAndPrint
+
+    let watchparser = ArgumentParser.Create<WatchArgs>(programName = "docstool")
+    let watchCLI =
+        [
+            WatchArgs.ProjectGlob srcGlob
+            WatchArgs.DocsOutputDirectory docsDir
+            WatchArgs.DocsSourceDirectory docsSrcDir
+            WatchArgs.GitHubRepoUrl gitHubRepoUrl
+            WatchArgs.ProjectName gitRepoName
+            WatchArgs.ReleaseVersion releaseNotes.NugetVersion
+        ]
+        |> watchparser.PrintCommandLineArgumentsFlat
+
+    let watch projectpath =
+        dotnet.watch (fun args ->
+           { args with WorkingDirectory = docsToolDir }
+        ) "run" (sprintf "-- watch %s" (watchCLI))
+        |> failOnBadExitAndPrint
+
 //-----------------------------------------------------------------------------
 // Target Implementations
 //-----------------------------------------------------------------------------
@@ -359,6 +417,36 @@ let formatCode _ =
         | _ -> ()
     )
 
+
+let buildDocs _ =
+    DocsTool.build ()
+
+let watchDocs _ =
+    let watchBuild () =
+        !! srcGlob
+        |> Seq.map(fun proj -> fun () ->
+            dotnet.watch
+                (fun opt ->
+                    opt |> DotNet.Options.withWorkingDirectory (IO.Path.GetDirectoryName proj))
+                "build"
+                ""
+            |> ignore
+        )
+        |> Seq.iter (invokeAsync >> Async.Catch >> Async.Ignore >> Async.Start)
+    watchBuild ()
+    DocsTool.watch ()
+
+let releaseDocs ctx =
+    isReleaseBranchCheck ()
+
+    Git.Staging.stageAll docsDir
+    Git.Commit.exec "" (sprintf "Documentation release of version %s" releaseNotes.NugetVersion)
+    if isRelease (ctx.Context.AllExecutingTargets) |> not then
+        // We only want to push if we're only calling "ReleaseDocs" target
+        // If we're calling "Release" target, we'll let the "GitRelease" target do the git push
+        Git.Branches.push ""
+
+
 //-----------------------------------------------------------------------------
 // Target Declaration
 //-----------------------------------------------------------------------------
@@ -377,12 +465,15 @@ Target.create "GitRelease" gitRelease
 Target.create "GitHubRelease" githubRelease
 Target.create "FormatCode" formatCode
 Target.create "Release" ignore
-
+Target.create "BuildDocs" buildDocs
+Target.create "WatchDocs" watchDocs
+Target.create "ReleaseDocs" releaseDocs
 
 //-----------------------------------------------------------------------------
 // Target Dependencies
 //-----------------------------------------------------------------------------
 
+
 // Only call Clean if DotnetPack was in the call chain
 // Ensure Clean is called before DotnetRestore
 "Clean" ?=> "DotnetRestore"
@@ -394,6 +485,14 @@ Target.create "Release" ignore
 "GenerateAssemblyInfo" ?=> "DotnetBuild"
 "GenerateAssemblyInfo" ==> "PublishToNuGet"
 
+"DotnetBuild" ==> "BuildDocs"
+"BuildDocs" ==> "ReleaseDocs"
+"BuildDocs" ?=> "PublishToNuget"
+"DotnetPack" ?=> "BuildDocs"
+"GenerateCoverageReport" ?=> "ReleaseDocs"
+
+"DotnetBuild" ==> "WatchDocs"
+
 "DotnetRestore"
     ==> "DotnetBuild"
     ==> "DotnetTest"

Content/Library/docsSrc/Explanations/Background.md

@@ -0,0 +1,3 @@
+# Background
+
+Here's a core concept and reasons why this exists at a deeper level.

Content/Library/docsSrc/How_Tos/Doing_A_Thing.md

@@ -0,0 +1,2 @@
+# How To do this specific thing
+

Content/Library/docsSrc/How_Tos/Doing_Another_Thing.md

@@ -0,0 +1,2 @@
+# How To do this specific thing
+

Content/Library/docsSrc/Tutorials/Getting_Started.md

@@ -0,0 +1,13 @@
+# Getting Started
+
+```fsharp
+let foo = ()
+let myAge = 21
+```
+
+## Here is the path to downloading 
+
+    [lang=bash]
+    paket install MyLib.1
+
+

Content/Library/docsSrc/content/hotload.js

@@ -0,0 +1,4 @@
+var refreshSocket = new WebSocket('ws://' + window.location.host)
+    .onmessage = () => {
+        location.reload();
+    }