improve default location abstractions

kMutagene · kMutagene · commit e28ee792f885 · 2023-11-28T09:37:00.000+01:00
- more descriptive class names
- member names now reflect paths exactly
- add badge svg file paths
- add location descriptions
diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -16,6 +16,7 @@
     <PackageVersion Include="Ionide.ProjInfo" Version="0.62.0" />
     <PackageVersion Include="Ionide.ProjInfo.Sln" Version="0.62.0" />
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
+    <PackageVersion Include="Spectre.Console" Version="0.48.0" />
     <PackageVersion Include="Suave" Version="2.6.2" />
     <PackageVersion Include="System.Memory" Version="4.5.5" />
     <PackageVersion Include="System.Text.Json" Version="8.0.0" />
diff --git a/build.fsx b/build.fsx
@@ -50,23 +50,28 @@ let testStage =
             $"dotnet test {solutionFile} --configuration {configuration} --no-build --blame --logger trx --results-directory TestResults -tl"
     }
 
-pipeline "CI" {
-    lintStage
+let buildStage =
+    stage "Build" {
+        run $"dotnet restore {solutionFile} -tl"
+        run $"dotnet build {solutionFile} --configuration {configuration} -tl"
+    }
 
+let cleanStage =
     stage "Clean" {
         run (fun _ ->
             !!artifactsDir ++ "temp" |> Shell.cleanDirs
             // in case the above pattern is empty as it only matches existing stuff
             [ "bin"; "temp"; "tests/bin" ] |> Seq.iter Directory.ensure)
     }
 
-    stage "Build" {
-        run $"dotnet restore {solutionFile} -tl"
-        run $"dotnet build {solutionFile} --configuration {configuration} -tl"
-    }
-
+let nugetStage =
     stage "NuGet" { run $"dotnet pack {solutionFile} --output \"{artifactsDir}\" --configuration {configuration} -tl" }
 
+pipeline "CI" {
+    lintStage
+    cleanStage
+    buildStage
+    nugetStage
     testStage
 
     stage "GenerateDocs" {
@@ -93,4 +98,11 @@ pipeline "Verify" {
     runIfOnlySpecified true
 }
 
+pipeline "BuildAndPack" {
+    cleanStage
+    buildStage
+    nugetStage
+    runIfOnlySpecified true
+}
+
 tryPrintPipelineCommandHelp ()
diff --git a/src/fsdocs-tool/BuildCommand.fs b/src/fsdocs-tool/BuildCommand.fs
@@ -2,6 +2,7 @@ namespace fsdocs
 
 open System.Collections.Concurrent
 open CommandLine
+open Spectre.Console
 
 open System
 open System.Diagnostics
@@ -1580,16 +1581,16 @@ type CoreBuildOptions(watch) =
         let dir = Path.GetDirectoryName(typeof<CoreBuildOptions>.Assembly.Location)
 
         // get template locations for in-package and in-repo and decide which to use later
-        let inPackageLocations = Common.InPackageLocations(Path.Combine(dir, "..", "..", ".."))
-        let inRepoLocations = Common.InRepoLocations(Path.Combine(dir, "..", "..", "..", "..", ".."))
+        let inNugetPackageLocations = Common.InNugetPackageLocations(Path.Combine(dir, "..", "..", ".."))
+        let inThisRepoLocations = Common.InDocsFolderLocations(Path.Combine(dir, "..", "..", "..", "..", "..", "docs"))
 
         let defaultTemplate =
             if this.nodefaultcontent then
                 None
-            else if inPackageLocations.Exist() then
-                Some inPackageLocations.template_html
-            elif inRepoLocations.Exist() then
-                Some inRepoLocations.template_html
+            else if inNugetPackageLocations.AllLocationsExist() then
+                Some inNugetPackageLocations.``templates/template.html``.Path
+            elif inThisRepoLocations.AllLocationsExist() then
+                Some inThisRepoLocations.``template.html``.Path
             else
                 None
 
@@ -1598,22 +1599,22 @@ type CoreBuildOptions(watch) =
                   // The "extras" content goes in "."
                   //   From .nuget\packages\fsdocs-tool\7.1.7\tools\net6.0\any
                   //   to .nuget\packages\fsdocs-tool\7.1.7\extras
-                  if inPackageLocations.Exist() then
-                      printfn "using extra content from %s" inPackageLocations.extras
-                      (inPackageLocations.extras, ".")
+                  if inNugetPackageLocations.AllLocationsExist() then
+                      printfn "using extra content from %s" inNugetPackageLocations.extras.Path
+                      (inNugetPackageLocations.extras.Path, ".")
                   else if
                       // This is for in-repo use only, assuming we are executing directly from
                       //   src\fsdocs-tool\bin\Debug\net6.0\fsdocs.exe
                       //   src\fsdocs-tool\bin\Release\net6.0\fsdocs.exe
-                      inRepoLocations.Exist()
+                      inThisRepoLocations.AllLocationsExist()
                   then
-                      printfn "using extra content from %s" inRepoLocations.docs_content
-                      (inRepoLocations.docs_content, "content")
+                      printfn "using extra content from %s" inThisRepoLocations.content.Path
+                      (inThisRepoLocations.content.Path, "content")
                   else
                       printfn
                           "no extra content found at %s or %s"
-                          inPackageLocations.extras
-                          inRepoLocations.docs_content ]
+                          inNugetPackageLocations.extras.Path
+                          inThisRepoLocations.content.Path ]
 
         // The incremental state (as well as the files written to disk)
         let mutable latestApiDocModel = None
@@ -1671,12 +1672,12 @@ type CoreBuildOptions(watch) =
                                     templateFiles
                                     d
 
-                                    OutputKind.Html, Some d
-                                | None ->
-                                    printfn
-                                        "note, no template file '%s' found, and no default template at '%s'"
-                                        templateFiles
-                                        inRepoLocations.template_html
+                                OutputKind.Html, Some d
+                            | None ->
+                                printfn
+                                    "note, no template file '%s' found, and no default template at '%s'"
+                                    templateFiles
+                                    inThisRepoLocations.``template.html``.Path
 
                                 OutputKind.Html, None
 
diff --git a/src/fsdocs-tool/InitCommand.fs b/src/fsdocs-tool/InitCommand.fs
@@ -3,47 +3,61 @@ namespace fsdocs
 open System.IO
 open CommandLine
 
+open Spectre.Console
+
 [<Verb("init", HelpText = "initialize the necessary folder structure and files for creating documentation with fsdocs.")>]
 type InitCommand() =
 
     let dir = Path.GetDirectoryName(typeof<InitCommand>.Assembly.Location)
 
     // get template locations for in-package and in-repo files and decide which to use later
-    let inPackageLocations = Common.InPackageLocations(Path.Combine(dir, "..", "..", ".."))
-    let inRepoLocations = Common.InRepoLocations(Path.Combine(dir, "..", "..", "..", "..", ".."))
+    let inNugetPackageLocations = Common.InNugetPackageLocations(Path.Combine(dir, "..", "..", ".."))
+    let inThisRepoLocations = Common.InDocsFolderLocations(Path.Combine(dir, "..", "..", "..", "..", "..", "docs"))
 
     [<Option("output",
              Required = false,
              Default = "docs",
              HelpText = "The output path for the documentation folder structure")>]
     member val output: string = "docs" with get, set
 
+    [<Option("force",
+             Required = false,
+             Default = false,
+             HelpText = "Whether to force-overwrite existing files in the output folder.")>]
+    member val force: bool = false with get, set
+
     member this.Execute() =
 
-        let outputPath = Path.GetFullPath(this.output)
-        let repoRoot = Path.GetFullPath(Path.Combine(outputPath, ".."))
-        let initLocations = Common.InRepoLocations(repoRoot)
+        let docsOutputPath = Path.GetFullPath(this.output)
+        let initLocations = Common.InDocsFolderLocations(docsOutputPath)
 
         let ensureOutputDirs () =
-            [ outputPath; initLocations.docs; initLocations.docs_img ]
+            [ docsOutputPath; initLocations.DocsFolder.Path; initLocations.img.Path ]
             |> List.iter ensureDirectory
 
-        if inPackageLocations.Exist() then
+        if inNugetPackageLocations.AllLocationsExist() then
             // if the in-package locations exist, this means fsdocs is run from the nuget package.
-            ensureOutputDirs ()
-
             try
-                [ (inPackageLocations.template_html, initLocations.template_html)
-                  (inPackageLocations.template_ipynb, initLocations.template_ipynb)
-                  (inPackageLocations.template_tex, initLocations.template_tex)
-                  (inPackageLocations.dockerfile, initLocations.dockerfile)
-                  (inPackageLocations.nuget_config, initLocations.nuget_config)
-                  // these files must be renamed, because files prefixed with a dot are otherwise ignored by fsdocs. We want this in the source repo, but not in the output of this command.
-                  (inPackageLocations.logo_template, Path.GetFullPath(Path.Combine(initLocations.docs_img, "logo.png")))
-                  (inPackageLocations.index_md_template, Path.GetFullPath(Path.Combine(initLocations.docs, "index.md")))
-                  (inPackageLocations.literate_sample_template,
-                   Path.GetFullPath(Path.Combine(initLocations.docs, "literate_sample.fsx"))) ]
-                |> List.iter (fun (src, dst) -> File.Copy(src, dst, true))
+                ensureOutputDirs ()
+
+                let fileMap =
+                    [ inNugetPackageLocations.``templates/template.html``, initLocations.``template.html``.Path
+                      inNugetPackageLocations.``templates/template.ipynb``, initLocations.``template.ipynb``.Path
+                      inNugetPackageLocations.``templates/template.tex``, initLocations.``template.tex``.Path
+                      inNugetPackageLocations.Dockerfile, initLocations.Dockerfile.Path
+                      inNugetPackageLocations.``Nuget.config``, initLocations.``Nuget.config``.Path
+                      inNugetPackageLocations.``extras/content/img/badge-binder.svg``, initLocations.``img/badge-binder.svg``.Path
+                      inNugetPackageLocations.``extras/content/img/badge-notebook.svg``, initLocations.``img/badge-notebook.svg``.Path
+                      inNugetPackageLocations.``extras/content/img/badge-script.svg``, initLocations.``img/badge-script.svg``.Path
+                      // these files must be renamed, because files prefixed with a dot are otherwise ignored by fsdocs. We want this in the source repo, but not in the output of this command.
+                      inNugetPackageLocations.``templates/init/.logo.png``,
+                      Path.GetFullPath(Path.Combine(initLocations.img.Path, "logo.png"))
+                      inNugetPackageLocations.``templates/init/.index_md_template.md``,
+                      Path.GetFullPath(Path.Combine(initLocations.DocsFolder.Path, "index.md"))
+                      inNugetPackageLocations.``templates/init/.literate_sample_template.fsx``,
+                      Path.GetFullPath(Path.Combine(initLocations.DocsFolder.Path, "literate_sample.fsx")) ]
+
+                fileMap |> List.iter (fun (src, dst) -> File.Copy(src.Path, dst, this.force))
 
                 printfn ""
                 printfn "a basic fsdocs scaffold has been created in %s." this.output
@@ -55,22 +69,32 @@ type InitCommand() =
                 printfn "Error: %s" exn.Message
                 1
 
-        elif inRepoLocations.Exist() then
+        elif inThisRepoLocations.AllLocationsExist() then
             // if the in-repo locations exist, this means fsdocs is run from inside the FSharp.Formatting repo itself.
-            ensureOutputDirs ()
 
             try
-                [ (inRepoLocations.template_html, initLocations.template_html)
-                  (inRepoLocations.template_ipynb, initLocations.template_ipynb)
-                  (inRepoLocations.template_tex, initLocations.template_tex)
-                  (inRepoLocations.dockerfile, initLocations.dockerfile)
-                  (inRepoLocations.nuget_config, initLocations.nuget_config)
-                  // these files must be renamed, because files prefixed with a dot are otherwise ignored by fsdocs. We want this in the source repo, but not in the output of this command.
-                  (inRepoLocations.logo_template, Path.GetFullPath(Path.Combine(initLocations.docs_img, "logo.png")))
-                  (inRepoLocations.index_md_template, Path.GetFullPath(Path.Combine(initLocations.docs, "index.md")))
-                  (inRepoLocations.literate_sample_template,
-                   Path.GetFullPath(Path.Combine(initLocations.docs, "literate_sample.fsx"))) ]
-                |> List.iter (fun (src, dst) -> File.Copy(src, dst, true))
+                ensureOutputDirs ()
+
+                let fileMap =
+                    [ (inThisRepoLocations.``template.html``, initLocations.``template.html``.Path)
+                      (inThisRepoLocations.``template.ipynb``, initLocations.``template.ipynb``.Path)
+                      (inThisRepoLocations.``template.tex``, initLocations.``template.tex``.Path)
+                      (inThisRepoLocations.Dockerfile, initLocations.Dockerfile.Path)
+                      (inThisRepoLocations.``Nuget.config``, initLocations.``Nuget.config``.Path)
+                      (inThisRepoLocations.``img/badge-binder.svg``, initLocations.``img/badge-binder.svg``.Path)
+                      (inThisRepoLocations.``img/badge-notebook.svg``, initLocations.``img/badge-notebook.svg``.Path)
+                      (inThisRepoLocations.``img/badge-script.svg``, initLocations.``img/badge-script.svg``.Path)
+                      // these files must be renamed, because files prefixed with a dot are otherwise ignored by fsdocs. We want this in the source repo, but not in the output of this command.
+                      (inThisRepoLocations.``templates/init/.logo.png``,
+                       Path.GetFullPath(Path.Combine(initLocations.img.Path, "logo.png")))
+                      (inThisRepoLocations.``templates/init/.index_md_template.md``,
+                       Path.GetFullPath(Path.Combine(initLocations.DocsFolder.Path, "index.md")))
+                      (inThisRepoLocations.``templates/init/.literate_sample_template.fsx``,
+                       Path.GetFullPath(Path.Combine(initLocations.DocsFolder.Path, "literate_sample.fsx"))) ]
+
+                fileMap
+                // |> List.map (fun (src, dst) -> )
+                |> List.iter (fun (src, dst) -> File.Copy(src.Path, dst, this.force))
 
                 printfn ""
                 printfn "a basic fsdocs scaffold has been created in %s." this.output
@@ -84,7 +108,7 @@ type InitCommand() =
         else
             printfn
                 "no sources for default files found from either %s or %s"
-                inPackageLocations.RelAssemblyPath
-                inRepoLocations.RelAssemblyPath
+                inNugetPackageLocations.NugetPackageRootPath.Path
+                inThisRepoLocations.DocsFolder.Path
 
             1
diff --git a/src/fsdocs-tool/Options.fs b/src/fsdocs-tool/Options.fs
diff --git a/src/fsdocs-tool/fsdocs-tool.fsproj b/src/fsdocs-tool/fsdocs-tool.fsproj
