Skip to content

Commit

Permalink
Merge branch 'main' into chore-migrate-to-xunit-v3
Browse files Browse the repository at this point in the history
  • Loading branch information
filzrev authored Dec 17, 2024
2 parents fbc6be3 + 445113c commit d444197
Show file tree
Hide file tree
Showing 107 changed files with 2,668 additions and 2,160 deletions.
5 changes: 5 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,11 @@ jobs:
env:
PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

- uses: codecov/codecov-action@v5
if: matrix.os == 'ubuntu-latest'
with:
fail_ci_if_error: true

- run: echo "DOTNET_DbgEnableMiniDump=1" >> $GITHUB_ENV
if: matrix.os == 'ubuntu-latest'

Expand Down
43 changes: 43 additions & 0 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
name: lint

on:
pull_request:
types:
- opened
- reopened
- synchronize
- ready_for_review
workflow_dispatch:

jobs:
build:
name: Lint
runs-on: ubuntu-latest
if: github.event.pull_request.draft == false
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Setup .NET SDK
uses: actions/setup-dotnet@v4
with:
dotnet-version: |
9.x
- name: Run `dotnet format` command
run: |
dotnet restore
dotnet format --no-restore --verify-no-changes
- name: Report failures as Job Summary
if: ${{ failure() }}
shell: pwsh
run: |
$content = '
## Failed to run the `lint.yml` workflow
To fix workflow errors. Please follow the steps below.
1. Run `dotnet format` command.
2. Commit changes as separated commit.
3. Push changes to source branch of PR.
'
Write-Output $content >> $env:GITHUB_STEP_SUMMARY
42 changes: 42 additions & 0 deletions .github/workflows/nightly.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
name: nightly
on:
workflow_dispatch:
schedule:
- cron: '0 0 * * *'

Expand Down Expand Up @@ -40,3 +41,44 @@ jobs:
run: |
dotnet nuget push drop/nuget/*.nupkg --api-key "${{ secrets.GITHUB_TOKEN }}" --skip-duplicate --source https://nuget.pkg.github.com/dotnet/index.json
test-nightly-package:
if: github.repository == 'dotnet/docfx'
runs-on: ubuntu-latest
needs: [publish-github-packages]
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
steps:

- name: Checkout
uses: actions/checkout@v4

- name: Create NuGet.config
shell: pwsh
run: |
@'
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<clear />
<add key="github" value="https://nuget.pkg.github.com/dotnet/index.json" />
</packageSources>
<packageSourceCredentials>
<github>
<add key="Username" value="%USER%" />
<add key="ClearTextPassword" value="%GITHUB_TOKEN%" />
</github>
</packageSourceCredentials>
</configuration>
'@ | Out-File NuGet.config -Encoding UTF8
- name: Install nightly build package
run: |
dotnet tool install docfx -g --prerelease
- name: Run docfx commands for test
working-directory: samples/seed
run: |
docfx metadata
docfx build
docfx pdf
16 changes: 4 additions & 12 deletions Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<PropertyGroup>
<ContinuousIntegrationBuild Condition="'$(GITHUB_ACTIONS)' == 'true'">true</ContinuousIntegrationBuild>
<TargetFrameworks>net8.0;net9.0</TargetFrameworks>
<TargetFrameworks Condition="'$(DOCFX_PREVIEW_BUILD)' == 'true'">net8.0;net9.0</TargetFrameworks>
<TargetFrameworks Condition="'$(DOCFX_PREVIEW_BUILD)' == 'true'">net8.0;net9.0</TargetFrameworks>
<LangVersion>Preview</LangVersion>
<ImplicitUsings>enable</ImplicitUsings>
<SuppressNETCoreSdkPreviewMessage>true</SuppressNETCoreSdkPreviewMessage>
Expand All @@ -19,9 +19,8 @@
warning NU1507: There are 2 package sources defined in your configuration.
warning NU5104: A stable release of a package should not have a prerelease dependency. Either modify the version spec of dependency "PdfPig [0.1.9-alpha-20240510-d86c2, )" or update the version field in the nuspec.
warning NU5111: The script file 'tools\.playwright\package\bin\install_media_pack.ps1' is not recognized by NuGet and hence will not be executed during installation of this package.
warning CS0436: IgnoresAccessChecksTo redefinition due to InternalsVisibleTo
-->
<NoWarn>$(NoWarn);NU1507;NU5104;NU5111;CS0436</NoWarn>
<NoWarn>$(NoWarn);NU1507;NU5104;NU5111</NoWarn>
</PropertyGroup>

<PropertyGroup>
Expand All @@ -30,8 +29,8 @@
<PublishRepositoryUrl>true</PublishRepositoryUrl>
<IncludeSymbols>true</IncludeSymbols>
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
<EmbedUntrackedSources>true</EmbedUntrackedSources>
<EmbedUntrackedSources>true</EmbedUntrackedSources>

<Authors>.NET Foundation and Contributors</Authors>
<Copyright>Copyright (c) .NET Foundation and Contributors</Copyright>
<Description>Technical documentation tool with markdown, API docs for .NET, REST API and more.</Description>
Expand All @@ -45,13 +44,6 @@
<None Include="$(MSBuildThisFileDirectory)\README.md" Pack="true" PackagePath="\"/>
</ItemGroup>

<ItemGroup>
<PackageReference Include="Microsoft.SourceLink.GitHub">
<PrivateAssets>all</PrivateAssets>
<IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
</ItemGroup>

<!-- Remove Node.js runtime dependencies that used by playwright -->
<Target Name="RemoveNodeJsRuntimes" AfterTargets="CopyPlaywrightFilesToOutput">
<ItemGroup>
Expand Down
39 changes: 15 additions & 24 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,12 @@
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="HtmlAgilityPack" Version="1.11.70" />
<PackageVersion Include="HtmlAgilityPack" Version="1.11.71" />
<PackageVersion Include="ICSharpCode.Decompiler" Version="8.2.0.7535" />
<PackageVersion Include="IgnoresAccessChecksToGenerator" Version="0.7.0" />
<PackageVersion Include="Jint" Version="4.1.0" />
<PackageVersion Include="JsonSchema.Net" Version="7.2.3" />
<PackageVersion Include="Markdig" Version="0.38.0" />
<PackageVersion Include="Microsoft.Playwright" Version="1.48.0" />
<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
<PackageVersion Include="Microsoft.Playwright" Version="1.49.0" />
<PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
<PackageVersion Include="OneOf" Version="3.0.271" />
<PackageVersion Include="OneOf.SourceGenerator" Version="3.0.271" />
Expand All @@ -20,32 +18,25 @@
<PackageVersion Include="Spectre.Console" Version="0.49.1" />
<PackageVersion Include="Spectre.Console.Cli" Version="0.49.1" />
<PackageVersion Include="Stubble.Core" Version="1.10.8" />
<PackageVersion Include="System.Collections.Immutable" Version="8.0.0" />
<PackageVersion Include="System.Composition" Version="8.0.0" />
<PackageVersion Include="System.Formats.Asn1" Version="8.0.1" />
<PackageVersion Include="System.Text.Json" Version="8.0.5" />
<PackageVersion Include="System.Collections.Immutable" Version="9.0.0" />
<PackageVersion Include="System.Composition" Version="9.0.0" />
<PackageVersion Include="System.Formats.Asn1" Version="9.0.0" />
<PackageVersion Include="System.Text.Json" Version="9.0.0" />
<PackageVersion Include="YamlDotNet" Version="15.3.0" />
</ItemGroup>

<ItemGroup>
<PackageVersion Include="Microsoft.CodeAnalysis" Version="4.11.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.11.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.11.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.11.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="4.11.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="4.11.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.11.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.11.0" />
<PackageVersion Include="Microsoft.CodeAnalysis" Version="4.12.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.12.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.12.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.12.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Workspaces" Version="4.12.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="4.12.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.12.0" />
<PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.12.0" />
</ItemGroup>

<ItemGroup>
<!-- Test only -->
<PackageVersion Include="coverlet.collector" Version="6.0.2" />
<PackageVersion Include="FluentAssertions" Version="6.12.1" />
<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
<PackageVersion Include="Verify.DiffPlex" Version="3.1.2" />
<PackageVersion Include="Verify.XunitV3" Version="28.1.3" />
<PackageVersion Include="xunit.runner.visualstudio" Version="3.0.0-pre.49" />
<PackageVersion Include="xunit.v3" Version="0.6.0-pre.7" />
<GlobalPackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
</ItemGroup>
</Project>
30 changes: 12 additions & 18 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -1,34 +1,28 @@
FROM mcr.microsoft.com/dotnet/sdk:8.0-bookworm-slim
FROM mcr.microsoft.com/dotnet/sdk:8.0-noble

# Add dotnet tools to path.
ENV PATH="${PATH}:/root/.dotnet/tools"

# Set Node.js path
ENV PLAYWRIGHT_NODEJS_PATH="/usr/bin/node"

# Set target docfx version.
ARG DOCFX_VERSION=2.77.0
ARG DOCFX_VERSION=2.78.2

# Install DocFX as a dotnet tool.
RUN dotnet tool install docfx -g --version ${DOCFX_VERSION} && \
docfx --version && \
rm -f /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/docfx.nupkg && \
rm -f /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/docfx.${DOCFX_VERSION}.nupkg && \
rm -rf /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net6.0

# Install Node.js and dependences for chromium PDF.
RUN apt-get update -qq && \
apt-get install -y -qq --no-install-recommends \
nodejs \
libglib2.0-0 libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
libdbus-1-3 libxcb1 libxkbcommon0 libatspi2.0-0 libx11-6 libxcomposite1 libxdamage1 \
libxext6 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2 && \
rm -rf /var/lib/apt/lists/* /tmp/*
rm -rf /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net9.0

# Install Chromium.
RUN PLAYWRIGHT_NODEJS_PATH="/usr/bin/node" && \
ln -s /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/.playwright /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net8.0/any/.playwright && \
pwsh -File /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net8.0/any/playwright.ps1 install chromium && \
unlink /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net8.0/any/.playwright
# Install Node.js and browser(chromium) with dependencies
RUN apt-get install -y -qq --update --no-install-recommends nodejs && \
pwsh -File /root/.dotnet/tools/.store/docfx/${DOCFX_VERSION}/docfx/${DOCFX_VERSION}/tools/net8.0/any/playwright.ps1 install --with-deps chromium && \
rm -rf /var/lib/apt/lists/* && \
rm -rf /tmp/*

WORKDIR /opt/prj
VOLUME [ "/opt/prj" ]

ENTRYPOINT [ "docfx" ]
ENTRYPOINT [ "docfx" ]
8 changes: 8 additions & 0 deletions docfx.sln
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{926A0726-B
ProjectSection(SolutionItems) = preProject
test\Directory.Build.props = test\Directory.Build.props
test\xunit.runner.json = test\xunit.runner.json
test\Directory.Packages.props = test\Directory.Packages.props
EndProjectSection
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "docfx", "src\docfx\docfx.csproj", "{EF53214F-BA98-4026-BEED-CF771865C312}"
Expand Down Expand Up @@ -98,6 +99,13 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Docfx.Build.OverwriteDocume
EndProject
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Docfx.Build.OverwriteDocuments.Tests", "test\Docfx.Build.OverwriteDocuments.Tests\Docfx.Build.OverwriteDocuments.Tests.csproj", "{CAECA6C3-3317-4E6E-8927-9186857B23E8}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{02EA681E-C7D8-13C7-8484-4AC65E1B71E8}"
ProjectSection(SolutionItems) = preProject
.editorconfig = .editorconfig
Directory.Build.props = Directory.Build.props
Directory.Packages.props = Directory.Packages.props
EndProjectSection
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Expand Down
49 changes: 48 additions & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ In this section we will build a simple documentation site on your local machine.
> Prerequisites
> - Familiarity with the command line
> - Install [.NET SDK](https://dotnet.microsoft.com/en-us/download) 8.0 or higher
> - Install [Node.js](https://nodejs.org/) v20 or higher
> - Install [Node.js](https://nodejs.org/) v20 or higher (Optional: It's required when using [Create PDF Files](https://filzrev.github.io/docfx/docs/pdf.html))
Make sure you have [.NET SDK](https://dotnet.microsoft.com/en-us/download) installed, then open a terminal and enter the following command to install the latest docfx:

Expand Down Expand Up @@ -114,6 +114,53 @@ await Docfx.Docset.Build("docfx.json");

See [API References](api/Docfx.yml) for additional APIs.

## How to use prerelease version of docfx

Docfx publishes nightly builds to [GitHub Packages](https://github.com/dotnet/docfx/pkgs/nuget/docfx).
If you want to use prerelease version, you can install package with following steps.

### Prerequisite

1. Install [GitHub CLI](https://github.com/cli/cli) command.
2. Install PowerShell 7.x or later.

### Steps

1. Open PowerShell on working directory.

2. Login to GitHub with additional scope request

```pwsh
gh auth login --scopes "read:packages" --host github.com
```
3. Follow the instructions and complete the login steps.
4. Download docfx nuget package from GitHub Packages
```pwsh
# Gets Access Token
$token = gh auth token
# Gets the version of latest nightly build
$version = gh api /orgs/dotnet/packages/nuget/docfx/versions --jq '.[0].name'
# Gets nupkg download URL.
$downloadUrl = "https://nuget.pkg.github.com/dotnet/download/docfx/${version}/${version}.nupkg"
# Download nupkg to current directory.
Write-Host ('Download nupkg from: {0}' -f $downloadUrl)
Invoke-RestMethod -Method Get -Uri $downloadUrl -OutFile "docfx.${version}.nupkg" -Headers @{
Authorization = "Bearer $token"
}
```
5. Install docfx as .NET Global Package from local source
```pwsh
dotnet tool update docfx -g --prerelease --source ./
```
## Next Steps
- [Write Articles](docs/markdown.md)
Expand Down
4 changes: 4 additions & 0 deletions docs/reference/docfx-cli-reference/docfx-metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,10 @@ Run `docfx metadata --help` or `docfx -h` to get a list of all available options

Disable the default API filter (default filter only generate public or protected APIs).

- **--noRestore**

Do not run `dotnet restore` before building the projects.

- **--namespaceLayout**

Determines the namespace layout in table of contents.
Expand Down
2 changes: 1 addition & 1 deletion samples/seed/docfx.json
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@
{ "files": [ "**" ], "src": "obj/md", "dest": "md" },
{ "files": [ "**" ], "src": "obj/apipage", "dest": "apipage" },
{ "files": [ "articles/**/*.{md,yml}", "*.md", "toc.yml", "restapi/**" ] },
{ "files": [ "pdf/**" ] }
{ "files": [ "pdf/*.{md,yml}" ] }
],
"resource": [
{
Expand Down
2 changes: 1 addition & 1 deletion samples/seed/dotnet/assembly/BuildFromAssembly.csproj
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<TargetFramework>net7.0</TargetFramework>
<TargetFramework>net8.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ public override ListWithStringFallback Read(ref Utf8JsonReader reader, Type type
{
using var document = JsonDocument.ParseValue(ref reader);
JsonElement root = document.RootElement;
var values = root.EnumerateObject().Select(x=>x.ToString());
var values = root.EnumerateObject().Select(x => x.ToString());
return new ListWithStringFallback(values);
}
default:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -65,4 +65,4 @@ public override void WriteJson(JsonWriter writer, object value, JsonSerializer s
serializer.Serialize(writer, ((MergeJsonConfig)value).ToArray());
}
}
}
}
Loading

0 comments on commit d444197

Please sign in to comment.