diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index b57f73a5..a333e70b 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -3,22 +3,32 @@ "isRoot": true, "tools": { "powershell": { - "version": "7.4.5", + "version": "7.4.6", "commands": [ "pwsh" - ] + ], + "rollForward": false }, "dotnet-coverage": { - "version": "17.12.5", + "version": "17.12.6", "commands": [ "dotnet-coverage" - ] + ], + "rollForward": false }, "nbgv": { - "version": "3.6.143", + "version": "3.6.146", "commands": [ "nbgv" - ] + ], + "rollForward": false + }, + "docfx": { + "version": "2.77.0", + "commands": [ + "docfx" + ], + "rollForward": false } } } \ No newline at end of file diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..6e6e64a0 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,41 @@ +name: 📚 Docs + +on: + push: + branches: + - main + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + actions: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + publish-docs: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: ⚙ Install prerequisites + run: ./init.ps1 -UpgradePrerequisites + + - run: dotnet docfx docfx/docfx.json + name: 📚 Generate documentation + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docfx/_site + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/libtemplate-update.yml b/.github/workflows/libtemplate-update.yml new file mode 100644 index 00000000..564d4af2 --- /dev/null +++ b/.github/workflows/libtemplate-update.yml @@ -0,0 +1,72 @@ +name: Library.Template update + +# PREREQUISITE: This workflow requires the repo to be configured to allow workflows to push commits and create pull requests. +# Visit https://github.com/USER/REPO/settings/actions +# Under "Workflow permissions", select "Read and write permissions" and check "Allow GitHub Actions to create ...pull requests" +# Click Save. + +on: + schedule: + - cron: "0 3 * * Mon" # Sun @ 8 or 9 PM Mountain Time (depending on DST) + workflow_dispatch: + +jobs: + merge: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # avoid shallow clone so nbgv can do its work. + + - name: merge + shell: pwsh + run: | + $LibTemplateBranch = & ./azure-pipelines/Get-LibTemplateBasis.ps1 -ErrorIfNotRelated + if ($LASTEXITCODE -ne 0) { + exit $LASTEXITCODE + } + + git fetch https://github.com/aarnott/Library.Template $LibTemplateBranch + if ($LASTEXITCODE -ne 0) { + exit $LASTEXITCODE + } + $LibTemplateCommit = git rev-parse FETCH_HEAD + + if ((git rev-list FETCH_HEAD ^HEAD --count) -eq 0) { + Write-Host "There are no Library.Template updates to merge." + exit 0 + } + + git -c http.extraheader="AUTHORIZATION: bearer $env:GH_TOKEN" push origin -u FETCH_HEAD:refs/heads/auto/libtemplateUpdate + - name: pull request + shell: pwsh + run: | + # If there is already an active pull request, don't create a new one. + $existingPR = gh pr list -H auto/libtemplateUpdate --json url | ConvertFrom-Json + if ($existingPR) { + Write-Host "::warning::Skipping pull request creation because one already exists at $($existingPR[0].url)" + exit 0 + } + + $prTitle = "Merge latest Library.Template" + $prBody = "This merges the latest features and fixes from [Library.Template's branch](https://github.com/AArnott/Library.Template/tree/). + +
+ Merge conflicts? + Resolve merge conflicts locally by carrying out these steps: + + ``` + git fetch + git checkout auto/libtemplateUpdate + git merge origin/main + # resolve conflicts + git commit + git push + ``` +
+ + ⚠️ Do **not** squash this pull request when completing it. You must *merge* it." + + gh pr create -H auto/libtemplateUpdate -b $prBody -t $prTitle + env: + GH_TOKEN: ${{ github.token }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e38dc47..70232cea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,3 +36,12 @@ The `nerdbank-streams` NPM package builds out of the `src/nerdbank-streams` dire Please review the [CONTRIBUTING.md](src/nerdbank-streams/CONTRIBUTING.md) document in that directory for instructions. [pwsh]: https://docs.microsoft.com/powershell/scripting/install/installing-powershell?view=powershell-6 + +## Tutorial and API documentation + +API and hand-written docs are found under the `docfx/` directory. and are built by [docfx](https://dotnet.github.io/docfx/). + +You can make changes and host the site locally to preview them by switching to that directory and running the `dotnet docfx --serve` command. +After making a change, you can rebuild the docs site while the localhost server is running by running `dotnet docfx` again from a separate terminal. + +The `.github/workflows/docs.yml` GitHub Actions workflow publishes the content of these docs to github.io if the workflow itself and [GitHub Pages is enabled for your repository](https://docs.github.com/en/pages/quickstart). diff --git a/Directory.Build.props b/Directory.Build.props index 431d5763..55919aae 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -56,7 +56,7 @@ - $(PackageProjectUrl)/releases/tag/v$(Version) + $(RepositoryUrl)/releases/tag/v$(Version) diff --git a/Directory.Packages.props b/Directory.Packages.props index a5881713..65ce1e87 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -37,7 +37,7 @@ - + diff --git a/azure-pipelines/collect-artifacts.yml b/azure-pipelines/collect-artifacts.yml index 1dfbbeef..c209db33 100644 --- a/azure-pipelines/collect-artifacts.yml +++ b/azure-pipelines/collect-artifacts.yml @@ -37,7 +37,7 @@ steps: - powershell: | $ArtifactStagingFolder = & "azure-pipelines/Get-ArtifactsStagingDirectory.ps1" $CoverageResultsFolder = Join-Path $ArtifactStagingFolder "coverageResults-$(Agent.JobName)" - azure-pipelines/publish-CodeCov.ps1 -CodeCovToken "$(codecov_token)" -PathToCodeCoverage "$CoverageResultsFolder" -Name "$(Agent.JobName) Coverage Results" -Flags "$(Agent.JobName)Host,$(BuildConfiguration)" + azure-pipelines/publish-CodeCov.ps1 -CodeCovToken "$(codecov_token)" -PathToCodeCoverage "$CoverageResultsFolder" -Name "$(Agent.JobName) Coverage Results" -Flags "$(Agent.JobName)" displayName: 📢 Publish code coverage results to codecov.io timeoutInMinutes: 3 continueOnError: true diff --git a/azure-pipelines/dotnet.yml b/azure-pipelines/dotnet.yml index b714145c..83188363 100644 --- a/azure-pipelines/dotnet.yml +++ b/azure-pipelines/dotnet.yml @@ -6,7 +6,7 @@ parameters: steps: -- script: dotnet build -t:build,pack --no-restore -c $(BuildConfiguration) -warnaserror /bl:"$(Build.ArtifactStagingDirectory)/build_logs/build.binlog" +- script: dotnet build -t:build,pack --no-restore -c $(BuildConfiguration) -warnAsError -warnNotAsError:NU1901,NU1902,NU1903,NU1904 /bl:"$(Build.ArtifactStagingDirectory)/build_logs/build.binlog" displayName: 🛠 dotnet build - powershell: azure-pipelines/dotnet-test-cloud.ps1 -Configuration $(BuildConfiguration) -Agent $(Agent.JobName) -PublishResults diff --git a/docfx/.gitignore b/docfx/.gitignore new file mode 100644 index 00000000..d5bcab17 --- /dev/null +++ b/docfx/.gitignore @@ -0,0 +1,2 @@ +_site/ +api/ diff --git a/docfx/docfx.json b/docfx/docfx.json new file mode 100644 index 00000000..14ed90dc --- /dev/null +++ b/docfx/docfx.json @@ -0,0 +1,48 @@ +{ + "metadata": [ + { + "src": [ + { + "src": "../src/Nerdbank.Streams", + "files": [ + "**/*.csproj" + ] + } + ], + "dest": "api" + } + ], + "build": { + "content": [ + { + "files": [ + "**/*.{md,yml}" + ], + "exclude": [ + "_site/**" + ] + } + ], + "resource": [ + { + "files": [ + "images/**" + ] + } + ], + "xref": [ + "https://learn.microsoft.com/en-us/dotnet/.xrefmap.json" + ], + "output": "_site", + "template": [ + "default", + "modern" + ], + "globalMetadata": { + "_appName": "Nerdbank.Streams", + "_appTitle": "Nerdbank.Streams", + "_enableSearch": true, + "pdf": false + } + } +} diff --git a/docfx/docs/features.md b/docfx/docs/features.md new file mode 100644 index 00000000..eb3fbeb0 --- /dev/null +++ b/docfx/docs/features.md @@ -0,0 +1,3 @@ +# Features + +TODO diff --git a/docfx/docs/getting-started.md b/docfx/docs/getting-started.md new file mode 100644 index 00000000..7880b401 --- /dev/null +++ b/docfx/docs/getting-started.md @@ -0,0 +1,12 @@ +# Getting Started + +## Installation + +Consume this library via its NuGet Package. +Click on the badge to find its latest version and the instructions for consuming it that best apply to your project. + +[![NuGet package](https://img.shields.io/nuget/v/Nerdbank.Streams.svg)](https://nuget.org/packages/Nerdbank.Streams) + +## Usage + +TODO diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml new file mode 100644 index 00000000..36a38020 --- /dev/null +++ b/docfx/docs/toc.yml @@ -0,0 +1,5 @@ +- name: Features + href: features.md +- name: Getting Started + href: getting-started.md + diff --git a/docfx/index.md b/docfx/index.md new file mode 100644 index 00000000..fc1b9e28 --- /dev/null +++ b/docfx/index.md @@ -0,0 +1,9 @@ +--- +_layout: landing +--- + +# Overview + +This is your docfx landing page. + +Click "Docs" across the top to get get started. diff --git a/docfx/toc.yml b/docfx/toc.yml new file mode 100644 index 00000000..abd17b8c --- /dev/null +++ b/docfx/toc.yml @@ -0,0 +1,4 @@ +- name: Docs + href: docs/ +- name: API + href: api/