diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json new file mode 100644 index 000000000..05b43454e --- /dev/null +++ b/.config/dotnet-tools.json @@ -0,0 +1,12 @@ +{ + "version": 1, + "isRoot": true, + "tools": { + "fsdocs-tool": { + "version": "20.0.0-alpha-009", + "commands": [ + "fsdocs" + ] + } + } +} \ No newline at end of file diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 439f5ccce..258358272 100644 --- 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 index d59a017c2..cb030ab6d 100644 --- 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 index 7ad752419..74f3eeb96 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ FSharp.Formatting/ FSharp.Core/obj/ tmp/ .idea/ +output/ \ No newline at end of file diff --git a/README.md b/README.md index 64dca2775..c5fa43ebf 100644 --- a/README.md +++ b/README.md @@ -9,45 +9,24 @@ signature files (`*.fsi`) in the FSharp.Core implementation. * Fork and clone 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 -* 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 - -* 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 -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.