Merge pull request #175 from nojaf/docs

Migrate documentation to fsdocs.

.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"
+      ]
     }
   }
 }

.github/workflows/push-main.yml

@@ -5,6 +5,11 @@ on:
     branches:
     - master
 
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
 jobs:
   build:
 
@@ -25,4 +30,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
+      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

.gitignore

@@ -163,7 +163,9 @@ $RECYCLE.BIN/
 packages/
 
 # Generated documentation folder
-docs/output/
+output/
+.fsdocs/
+tmp/
 
 # Temp folder used for publishing docs
 temp/

Directory.Build.props

@@ -0,0 +1,9 @@
+<Project>
+    <PropertyGroup>
+        <FsDocsLicenseLink>https://github.com/fsprojects/fslexYacc/blob/master/LICENSE.txt</FsDocsLicenseLink>
+        <FsDocsReleaseNotesLink>https://github.com/fsprojects/FsLexYacc/blob/master/RELEASE_NOTES.md</FsDocsReleaseNotesLink>
+        <RepositoryUrl>https://github.com/fsprojects/FsLexYacc/</RepositoryUrl>
+        <FsDocsLogoSource>img/logo.png</FsDocsLogoSource>
+        <FsDocsFaviconSource>img/favicon.ico</FsDocsFaviconSource>
+    </PropertyGroup>
+</Project>

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

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,28 +188,17 @@ 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")
 
 // --------------------------------------------------------------------------------------
 // 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"
 

docs/content/fslex.md

@@ -1,4 +1,4 @@
-Overview
+FsLex Overview
 ========
 
 The `fslex` tool is a lexer generator for byte and Unicode character input.

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)

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).