Skip to content

Commit

Permalink
improve default location abstractions
Browse files Browse the repository at this point in the history 
- more descriptive class names
- member names now reflect paths exactly
- add badge svg file paths
- add location descriptions
  • Loading branch information
@kMutagene
kMutagene committed Nov 28, 2023
1 parent f5bd211 commit e28ee79
Show file tree
Hide file tree
Showing 6 changed files with 313 additions and 148 deletions.
1 change: 1 addition & 0 deletions Directory.Packages.props
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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" />
Expand Down
26 changes: 19 additions & 7 deletions build.fsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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" {
Expand All @@ -93,4 +98,11 @@ pipeline "Verify" {
runIfOnlySpecified true
}

pipeline "BuildAndPack" {
cleanStage
buildStage
nugetStage
runIfOnlySpecified true
}

tryPrintPipelineCommandHelp ()
41 changes: 21 additions & 20 deletions src/fsdocs-tool/BuildCommand.fs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ namespace fsdocs

open System.Collections.Concurrent
open CommandLine
open Spectre.Console

open System
open System.Diagnostics
Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down
94 changes: 59 additions & 35 deletions src/fsdocs-tool/InitCommand.fs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Loading

0 comments on commit e28ee79

Please sign in to comment.