Merge pull request #95 from nojaf/update-fsdocs

Update fsdocs
fsharp · Nov 11, 2023 · fe8bbca · fe8bbca
2 parents ab1d7d9 + b5c6872
commit fe8bbca
Show file tree

Hide file tree

Showing 5 changed files with 32 additions and 70 deletions.
diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json
@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "fsdocs-tool": {
+      "version": "20.0.0-alpha-009",
+      "commands": [
+        "fsdocs"
+      ]
+    }
+  }
+}
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -11,48 +11,36 @@ on:
 
 env:
   FSHARP_DIR: fsharp
-  FSF_DIR: FSharp.Formatting
 
 jobs:
   build:
     runs-on: windows-latest
     steps:
       - uses: actions/checkout@v3
+      - name: Restore tools
+        run: dotnet tool restore
       - name: Checkout fsharp main
         uses: actions/checkout@v3
         with:
           repository: dotnet/fsharp
           path: ${{ env.FSHARP_DIR }}
           ref: main
-      - name: Checkout FSharp.Formatting main
-        uses: actions/checkout@v3
-        with:
-          repository: fsprojects/FSharp.Formatting
-          path: ${{ env.FSF_DIR }}
-          ref: main
       - name: Setup .NET for FSharp
         uses: actions/setup-dotnet@v3
         with:
           global-json-file: ${{ env.FSHARP_DIR }}/global.json
-      - name: Setup .NET for FSharp.Formatting
-        uses: actions/setup-dotnet@v3
-        with:
-          global-json-file: ${{ env.FSF_DIR }}/global.json
       - name: Restore local FSharp.Core project in current repo
         run: dotnet restore FSharp.Core\FSharp.Core.fsproj
       - name: Build FSharp.Core in fsharp main
         run: dotnet build src\FSharp.Core\FSharp.Core.fsproj /p:BUILDING_USING_DOTNET=true
         working-directory: ${{ env.FSHARP_DIR }}
-      - name: Build FSharp.Formatting main
-        run: dotnet fsi ./build.fsx -t Build
-        working-directory: ${{ env.FSF_DIR }}
       - name: Run fsdocs
         env:
           # allow roll forward to latest major version - this would happen for us if we invoked the fsdocs tool instead of invoking the binary directly
           DOTNET_ROLL_FORWARD: "LatestMajor"
           # need previews because .NET 8 is what's being used at runtime
           DOTNET_ROLL_FORWARD_TO_PRERELEASE: "1"
-        run: dotnet FSharp.Formatting\src\fsdocs-tool\bin\Release\net6.0\fsdocs.dll build --sourcefolder ${{ env.FSHARP_DIR }}
+        run: dotnet fsdocs build --sourcefolder ${{ env.FSHARP_DIR }}
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         with:

diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
@@ -21,32 +21,21 @@ jobs:
           repository: dotnet/fsharp
           path: ${{ env.FSHARP_DIR }}
           ref: main
-      - name: Checkout FSharp.Formatting main
-        uses: actions/checkout@v3
-        with:
-          repository: fsprojects/FSharp.Formatting
-          path: ${{ env.FSF_DIR }}
-          ref: main
       - name: Setup .NET for FSharp
         uses: actions/setup-dotnet@v3
         with:
           global-json-file: ${{ env.FSHARP_DIR }}/global.json
-      - name: Setup .NET for FSharp.Formatting
-        uses: actions/setup-dotnet@v3
-        with:
-          global-json-file: ${{ env.FSF_DIR }}/global.json
+      - name: Restore tools
+        run: dotnet tool restore
       - name: Restore local FSharp.Core project in current repo
         run: dotnet restore FSharp.Core\FSharp.Core.fsproj
       - name: Build FSharp.Core in fsharp main
         run: dotnet build src\FSharp.Core\FSharp.Core.fsproj /p:BUILDING_USING_DOTNET=true
         working-directory: ${{ env.FSHARP_DIR }}
-      - name: Build FSharp.Formatting main
-        run: dotnet fsi ./build.fsx -t Build
-        working-directory: ${{ env.FSF_DIR }}
       - name: Run fsdocs
         env:
           # allow roll forward to latest major version - this would happen for us if we invoked the fsdocs tool instead of invoking the binary directly
           DOTNET_ROLL_FORWARD: "LatestMajor"
           # need previews because .NET 8 is what's being used at runtime
           DOTNET_ROLL_FORWARD_TO_PRERELEASE: "1"
-        run: dotnet FSharp.Formatting/src/fsdocs-tool/bin/Release/net6.0/fsdocs.dll build --sourcefolder ${{ env.FSHARP_DIR }}
+        run: dotnet fsdocs build --sourcefolder ${{ env.FSHARP_DIR }}
diff --git a/.gitignore b/.gitignore
@@ -10,3 +10,4 @@ FSharp.Formatting/
 FSharp.Core/obj/
 tmp/
 .idea/
+output/
diff --git a/README.md b/README.md
@@ -9,45 +9,24 @@ signature files (`*.fsi`) in the FSharp.Core implementation.
 
 * Fork and clone <https://github.com/dotnet/fsharp> locally, see below, as a subdirectory of your copy of `fsharp-core-docs`
 
-* Contribute to [the FSharp.Core directory](https://github.com/dotnet/fsharp/tree/master/src/fsharp/FSharp.Core)
-
-* Use a local build, see below
+* Contribute to [the FSharp.Core directory](https://github.com/dotnet/fsharp/tree/main/src/fsharp/FSharp.Core)
 
 * Submit work to  `main` branch of <https://github.com/dotnet/fsharp>
 
-* Once accepted your work will be published through a rebuild here. Site rebuilds daily at 17:30 UTC, or submit a dummy pull request here to trigger.
+* Update the `dotnet tool` if new versions are released.
 
 ## Contributing to Generation of API Docs
 
 The docs are generated by using `fsdocs` tool from FSharp.Formatting.  If you want to improve the generation process:
 
-* Contribute to the API Docs mode and/or HTML generator in [FSharp.Formatting.ApiDocs](https://github.com/fsprojects/FSharp.Formatting/tree/master/src/FSharp.Formatting.ApiDocs) and [the `fsdocs` tool](https://github.com/fsprojects/FSharp.Formatting/tree/master/src/FSharp.Formatting.CommandTool)
-
-* Use a local copy of these, see below, as a subdirectory of fsharp-core-docs
-
-* Submit work to the `master` branch of <https://github.com/fsprojects/FSharp.Formatting>
-
-* Once accepted the new tooling will be published through a rebuild here, so submit a dummy pull request here that increments dummyVersion.txt
-
-## Contributing to Layout and Design
-
-These pages are currently using [the default template of the FSharp.Formatting tools](https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/_template.html)
-with its small amount of corresponding [CSS and JavaScript](https://github.com/fsprojects/FSharp.Formatting/tree/master/docs/content)
-
-See [FSharp.Formatting styling](https://fsprojects.github.io/FSharp.Formatting/styling.html) for information on styling for output generated by `fsdocs`.
+* Contribute to the API Docs mode and/or HTML generator in [FSharp.Formatting.ApiDocs](https://github.com/fsprojects/FSharp.Formatting/tree/main/src/FSharp.Formatting.ApiDocs) and [the `fsdocs` tool](https://github.com/fsprojects/FSharp.Formatting/tree/main/src/FSharp.Formatting.CommandTool)
 
-This template is *not* the long term plan (unless it is improved enough).  We can improve the design - please help with this.  
+* Submit work to the `main` branch of <https://github.com/fsprojects/FSharp.Formatting>
 
-1. Copy the default template and CSS to `docs`.  Rebuild as before.  This  template will be used instead of the default template.
-
-2. After you have identified fixes and improvements, contribute back to the default template of FSharp.Formatting, or submit your work here and we can assess that.  This will help improve many F# libraries.
-
-Whatever improvements you make should eventually get copied across back into FSharp.Formatting (and the duplicated template and styling will then likely be removed from this repo once it's no longer needed). If the design diverges to be a completely different look and feel then we can make several templates available in FSharp.Formatting with this as one of them.
+* Update the `dotnet tool` if new versions are released.
 
 ## Build steps
 
-Eventually the build will just be
-
     dotnet tool restore
     dotnet restore FSharp.Core
     dotnet fsdocs build
@@ -56,34 +35,27 @@ For now, we want to pick up the latest copies of FSharp.Formatting and FSharp.Co
 
     (start in 'fsharp-core-docs')
     dotnet restore FSharp.Core
+    dotnet tool restore
 
-    (make 'fsharp-core-docs/fsharp' and 'fsharp-core-docs/FSharp.Formatting' )
+    (make fsharp-compiler-docs/fsharp)
     git clone https://github.com/dotnet/fsharp --depth 1 -b main
-    git clone https://github.com/fsprojects/FSharp.Formatting --depth 1
 
     (build 'fsharp-core-docs/fsharp')
     pushd fsharp
-    .\build -noVisualStudio
-    popd
-
-    (build 'fsharp-core-docs/FSharp.Formatting')
-    pushd FSharp.Formatting
-    .\build -t Build
+    dotnet build src\FSharp.Core\FSharp.Core.fsproj /p:BUILDING_USING_DOTNET=true
     popd
 
 Then do iterative development using:
 
     (from 'fsharp-core-docs')
-    FSharp.Formatting\src\FSharp.Formatting.CommandTool\bin\Release\netcoreapp3.1\fsdocs.exe watch --sourcefolder fsharp  
+    dotnet fsdocs watch --sourcefolder fsharp
 
 ## CI Pipeline
 
-This repo is published via GitHub Actions. On each push to master, the docs are built, and the outputs (which are written to the `output` directory by fsdocs) are pushed to the `gh-pages` branch. This repo is configured to host using GitHub Pages from this branch, so once the generated files are pushed the update is nearly-instant.
-
-To build the very latest and freshest docs using the latest `fsdocs` tooling the CI does this:
+This repo is published via GitHub Actions. On each push to main, the docs are built, and the outputs (which are written to the `output` directory by fsdocs) are pushed to the `gh-pages` branch. This repo is configured to host using GitHub Pages from this branch, so once the generated files are pushed the update is nearly-instant.
 
-1. build dotnet/fsharp `main` branch (where we assume latest doc updates have been pushed)
+To build the very latest and freshest docs the CI does this:
 
-2. builds `FSharp.Formatting` master branch
+1. build dotnet/fsharp `main` branch (where we assume latest doc updates have been pushed).
 
-3. Uses that `FSharp.Formatting` tool to build the docs for the FSharp.Core built in step 1
+2. generate the documentation using the local dotnet fsdocs tool.