From 53b284219b649896323da4f3e5fb8151b74333dc Mon Sep 17 00:00:00 2001 From: nojaf Date: Sat, 11 Nov 2023 10:24:25 +0100 Subject: [PATCH 1/2] Migrate documentation to fsdocs. --- .config/dotnet-tools.json | 12 +-- .github/workflows/push-main.yml | 16 ++- .gitignore | 4 +- Directory.Build.props | 9 ++ FsLexYacc.sln | 8 -- build.fsx | 21 +--- docs/content/fslex.md | 2 +- docs/content/fsyacc.md | 2 +- docs/content/jsonParserExample.md | 9 -- docs/generate.fsx | 157 ------------------------------ docs/img/favicon.ico | Bin 0 -> 12014 bytes docs/{files => }/img/logo.pdn | Bin docs/{files => }/img/logo.png | Bin docs/{content => }/index.fsx | 0 docs/templates/template.cshtml | 55 ----------- 15 files changed, 40 insertions(+), 255 deletions(-) create mode 100644 Directory.Build.props delete mode 100644 docs/generate.fsx create mode 100644 docs/img/favicon.ico rename docs/{files => }/img/logo.pdn (100%) rename docs/{files => }/img/logo.png (100%) rename docs/{content => }/index.fsx (100%) delete mode 100644 docs/templates/template.cshtml diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index b55da38e..f64e0770 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -14,17 +14,17 @@ "paket" ] }, - "dotnet-serve": { - "version": "1.10.149", - "commands": [ - "dotnet-serve" - ] - }, "fantomas": { "version": "6.0.2", "commands": [ "fantomas" ] + }, + "fsdocs-tool": { + "version": "20.0.0-alpha-008", + "commands": [ + "fsdocs" + ] } } } \ No newline at end of file diff --git a/.github/workflows/push-main.yml b/.github/workflows/push-main.yml index 3b34f61e..71ab6fbf 100644 --- a/.github/workflows/push-main.yml +++ b/.github/workflows/push-main.yml @@ -25,4 +25,18 @@ jobs: - name: Build run: dotnet fake run build.fsx -t Release - name: Publish NuGets (if main version changed) - run: dotnet nuget push "bin/*.nupkg" -s https://api.nuget.org/v3/index.json -k ${{ secrets.NUGET_KEY }} --skip-duplicate \ No newline at end of file + run: dotnet nuget push "bin/*.nupkg" -s https://api.nuget.org/v3/index.json -k ${{ secrets.NUGET_KEY }} --skip-duplicate + - name: Build documentation + run: dotnet fake run build.fsx -t GenerateDocs + - name: Upload documentation + uses: actions/upload-pages-artifact@v1 + with: + path: ./output + + docs: + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 diff --git a/.gitignore b/.gitignore index 67ca7588..6059d3da 100644 --- a/.gitignore +++ b/.gitignore @@ -163,7 +163,9 @@ $RECYCLE.BIN/ packages/ # Generated documentation folder -docs/output/ +output/ +.fsdocs/ +tmp/ # Temp folder used for publishing docs temp/ diff --git a/Directory.Build.props b/Directory.Build.props new file mode 100644 index 00000000..ef47c7b5 --- /dev/null +++ b/Directory.Build.props @@ -0,0 +1,9 @@ + + + https://github.com/fsprojects/fslexYacc/blob/master/LICENSE.txt + https://github.com/fsprojects/FsLexYacc/blob/master/RELEASE_NOTES.md + https://github.com/fsprojects/FsLexYacc/ + img/logo.png + img/favicon.ico + + \ No newline at end of file diff --git a/FsLexYacc.sln b/FsLexYacc.sln index c59fd4ff..aa0482c2 100644 --- a/FsLexYacc.sln +++ b/FsLexYacc.sln @@ -20,14 +20,6 @@ EndProject Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "LexAndYaccMiniProject", "tests\LexAndYaccMiniProject\LexAndYaccMiniProject.fsproj", "{91D0BE7A-E128-498A-BB68-6ED65A582E04}" EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{4BB66375-380B-4EBD-9BA6-40CE92EB3D98}" - ProjectSection(SolutionItems) = preProject - docs\content\fslex.md = docs\content\fslex.md - docs\content\fsyacc.md = docs\content\fsyacc.md - docs\generate.fsx = docs\generate.fsx - docs\content\index.fsx = docs\content\index.fsx - docs\content\jsonParserExample.md = docs\content\jsonParserExample.md - docs\templates\template.cshtml = docs\templates\template.cshtml - EndProjectSection EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{884C599D-FDE2-4AC3-828A-12F6C662F273}" EndProject diff --git a/build.fsx b/build.fsx index 42531ab8..a4c9a325 100644 --- a/build.fsx +++ b/build.fsx @@ -113,7 +113,7 @@ Target.create "AssemblyInfo" (fun _ -> Target.create "Clean" (fun _ -> Shell.cleanDirs [ "bin"; "temp" ]) -Target.create "CleanDocs" (fun _ -> Shell.cleanDirs [ "docs/output" ]) +Target.create "CleanDocs" (fun _ -> Shell.cleanDirs [ "output"; ".fsdocs" ]) // -------------------------------------------------------------------------------------- // Build library & test project @@ -188,10 +188,10 @@ Target.create "GenerateDocs" (fun _ -> DotNet.exec (fun p -> { p with - WorkingDirectory = __SOURCE_DIRECTORY__ @@ "docs" + WorkingDirectory = __SOURCE_DIRECTORY__ }) - "fsi" - "--define:RELEASE --define:REFERENCE --define:HELP --exec generate.fsx" + "fsdocs" + "build --eval" if not result.OK then failwith "error generating docs") @@ -199,17 +199,6 @@ Target.create "GenerateDocs" (fun _ -> // -------------------------------------------------------------------------------------- // Release Scripts -Target.create "ReleaseDocs" (fun _ -> - let tempDocsDir = "temp/gh-pages" - Shell.cleanDir tempDocsDir - Repository.cloneSingleBranch "" (gitHome + "/" + gitName + ".git") "gh-pages" tempDocsDir - - Repository.fullclean tempDocsDir - Shell.copyRecursive "docs/output" tempDocsDir true |> Trace.tracefn "%A" - Staging.stageAll tempDocsDir - Commit.exec tempDocsDir (sprintf "Update generated documentation for version %s" release.NugetVersion) - Branches.push tempDocsDir) - Target.create "Release" ignore // -------------------------------------------------------------------------------------- @@ -225,7 +214,7 @@ Target.create "All" ignore ==> "RunOldFsYaccTests" ==> "All" -"All" ==> "CleanDocs" ==> "GenerateDocs" ==> "ReleaseDocs" +"CleanDocs" ==> "Build" ==> "GenerateDocs" "Build" ==> "NuGet" diff --git a/docs/content/fslex.md b/docs/content/fslex.md index a23add66..e3262356 100644 --- a/docs/content/fslex.md +++ b/docs/content/fslex.md @@ -1,4 +1,4 @@ -Overview +FsLex Overview ======== The `fslex` tool is a lexer generator for byte and Unicode character input. diff --git a/docs/content/fsyacc.md b/docs/content/fsyacc.md index c9341251..608b28df 100644 --- a/docs/content/fsyacc.md +++ b/docs/content/fsyacc.md @@ -1,4 +1,4 @@ -Overview +FsYacc Overview ======== `fsyacc` is a `LALR` parser generator. It follows a similar specification to the `OCamlYacc` parser generator (especially when used with the `ml compatibility` switch) diff --git a/docs/content/jsonParserExample.md b/docs/content/jsonParserExample.md index 0860991a..51f5a1f9 100644 --- a/docs/content/jsonParserExample.md +++ b/docs/content/jsonParserExample.md @@ -1,15 +1,6 @@ Building JSON parser using FsLex and FsYacc =========================================== -Content: - -1. [Introduction](#introduction) -2. [Syntax tree](#syntaxtree) -3. [Parser](#parser) -4. [Lexer](#lexer) -5. [Program](#program) - - 1 Introduction ---------------- FsLexYacc is a solution which allows you to define and generate lexer and parser. It's made of two parts FsLex (lexer generator) and FsYacc (parser generator). Parsing is a two phase process. In the first phase lexer is analyzing text and creates a stream of tokens (or token list). In the second phase parser is going through tokens in the stream and generates output (syntax tree). diff --git a/docs/generate.fsx b/docs/generate.fsx deleted file mode 100644 index 8648a01d..00000000 --- a/docs/generate.fsx +++ /dev/null @@ -1,157 +0,0 @@ -// -------------------------------------------------------------------------------------- -// Builds the documentation from `.fsx` and `.md` files in the 'docs/content' directory -// (the generated documentation is stored in the 'docs/output' directory) -// -------------------------------------------------------------------------------------- - -#load "../packages/FSharp.Formatting/FSharp.Formatting.fsx" - -open System.Collections.Generic -open System.IO -open FSharp.Formatting.Razor - -// -------------------------------------------------------------------------------------- -// Helpers -// -------------------------------------------------------------------------------------- -let subDirectories (dir: string) = Directory.EnumerateDirectories dir - -let rec copyRecursive dir1 dir2 = - Directory.CreateDirectory dir2 |> ignore - - for subdir1 in Directory.EnumerateDirectories dir1 do - let subdir2 = Path.Combine(dir2, Path.GetFileName subdir1) - copyRecursive subdir1 subdir2 - - for file in Directory.EnumerateFiles dir1 do - File.Copy(file, file.Replace(dir1, dir2), true) - -// -------------------------------------------------------------------------------------- -// Settings -// -------------------------------------------------------------------------------------- - -// Binaries that have XML documentation (in a corresponding generated XML file) -let referenceBinaries = - [ - __SOURCE_DIRECTORY__ - + "/../src/FsLexYacc.Runtime/bin/Release/netstandard2.0/FsLexYacc.Runtime.dll" - ] - -let githubLink = "http://github.com/fsprojects/FsLexYacc" - -// Specify more information about your project -let info = - [ - "project-name", "FsLexYacc" - "project-author", "FsLexYacc contributors" - "project-summary", "Lex and Yacc for F#" - "project-github", githubLink - "project-nuget", "https://www.nuget.org/packages/FsLexYacc/" - ] - -// -------------------------------------------------------------------------------------- -// For typical project, no changes are needed below -// -------------------------------------------------------------------------------------- - -// When called from 'build.fsx', use the public project URL as -// otherwise, use the current 'output' directory. -let root = "/FsLexYacc" - -Directory.SetCurrentDirectory(__SOURCE_DIRECTORY__) - -// Paths with template/source/output locations -let bin = - __SOURCE_DIRECTORY__ + "/../src/FsLexYacc.Runtime/bin/Release/netstandard2.0" - -let output = __SOURCE_DIRECTORY__ + "/output" -let contentIn = __SOURCE_DIRECTORY__ + "/content" -let files = __SOURCE_DIRECTORY__ + "/files" -let templates = __SOURCE_DIRECTORY__ + "/templates" -let formatting = __SOURCE_DIRECTORY__ + "/../packages/FSharp.Formatting/" -let docTemplate = formatting + "/templates/docpage.cshtml" -let referenceOut = output + "/reference" -let contentOut = output + "/content" - -// Where to look for *.csproj templates (in this order) -let layoutRootsAll = Dictionary() - -layoutRootsAll.Add( - "en", - [ - templates - formatting + "/" + "templates" - formatting + "/" + "templates/reference" - ] -) - -subDirectories templates -|> Seq.iter (fun name -> - if name.Length = 2 || name.Length = 3 then - layoutRootsAll.Add( - name, - [ - templates + "/" + name - formatting + "/" + "templates" - formatting + "/" + "templates/reference" - ] - )) - -// Copy static files and CSS + JS from F# Formatting -let copyFiles () = - copyRecursive files output - copyRecursive (formatting + "/styles") contentOut - -let libDirs = [ bin ] - -// Build API reference from XML comments -let buildReference () = - printfn "building reference docs..." - - if Directory.Exists referenceOut then - Directory.Delete(referenceOut, true) - - Directory.CreateDirectory referenceOut |> ignore - - RazorMetadataFormat.Generate( - referenceBinaries, - output + "/" + "reference", - layoutRootsAll.["en"], - parameters = ("root", root) :: info, - sourceRepo = githubLink + "/" + "tree/master", - sourceFolder = __SOURCE_DIRECTORY__ + "/" + ".." + "/" + "..", - publicOnly = true, - libDirs = libDirs - ) - -// Build documentation from `fsx` and `md` files in `docs/content` -let buildDocumentation () = - printfn "building docs..." - let subdirs = [ (contentIn, docTemplate) ] - - for dir, template in subdirs do - let sub = "." // Everything goes into the same output directory here - - let langSpecificPath (lang, path: string) = - path.Split([| '/'; '\\' |], System.StringSplitOptions.RemoveEmptyEntries) - |> Array.exists (fun i -> i = lang) - - let layoutRoots = - let key = layoutRootsAll.Keys |> Seq.tryFind (fun i -> langSpecificPath (i, dir)) - - match key with - | Some lang -> layoutRootsAll.[lang] - | None -> layoutRootsAll.["en"] // "en" is the default language - - RazorLiterate.ProcessDirectory( - dir, - template, - output + "/" + sub, - replacements = ("root", root) :: info, - layoutRoots = layoutRoots, - generateAnchors = true, - processRecursive = false, - includeSource = true - ) - -// Generate -copyFiles () -buildDocumentation () -buildReference () diff --git a/docs/img/favicon.ico b/docs/img/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..043457fde280b78a521bdcb3db2062fa602f5cf6 GIT binary patch literal 12014 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 bNqTM9+OKi#95AEqE#iic-`1(x_~QQp`(HMc literal 0 HcmV?d00001 diff --git a/docs/files/img/logo.pdn b/docs/img/logo.pdn similarity index 100% rename from docs/files/img/logo.pdn rename to docs/img/logo.pdn diff --git a/docs/files/img/logo.png b/docs/img/logo.png similarity index 100% rename from docs/files/img/logo.png rename to docs/img/logo.png diff --git a/docs/content/index.fsx b/docs/index.fsx similarity index 100% rename from docs/content/index.fsx rename to docs/index.fsx diff --git a/docs/templates/template.cshtml b/docs/templates/template.cshtml deleted file mode 100644 index b361628c..00000000 --- a/docs/templates/template.cshtml +++ /dev/null @@ -1,55 +0,0 @@ - - - - - @Title - - - - - - - - - - - - - -
-
- -

@Properties["project-name"]

-
-
-
-
- @RenderBody() -
-
- F# Project - -
-
-
- Fork me on GitHub - - From 5f7b8db989df629e517628a0fd215c27571779de Mon Sep 17 00:00:00 2001 From: nojaf Date: Sat, 11 Nov 2023 10:30:51 +0100 Subject: [PATCH 2/2] Add additional permissions required to deploy to GH pages. --- .github/workflows/push-main.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/push-main.yml b/.github/workflows/push-main.yml index 71ab6fbf..33de153f 100644 --- a/.github/workflows/push-main.yml +++ b/.github/workflows/push-main.yml @@ -5,6 +5,11 @@ on: branches: - master +permissions: + contents: read + pages: write + id-token: write + jobs: build: