From bfb78e937fb9d4f4273bbac9c85e4d69d62e3b04 Mon Sep 17 00:00:00 2001 From: Bjarke Berg Date: Thu, 18 Mar 2021 14:48:22 +0100 Subject: [PATCH] Netcore: Update code docs generation (#9885) * Updated the code docs to work with new assemblies and namespaces+added conditional build to default pipeline * updated script that generate docs to use .NET 5 * Increased timeout of docs generation + changed to 5.x instead of 5.0.x Fixed wrong namespace, that would be we not have docs for it. * Fixed names in toc, so they are not that long and changed ordering * try custom hack https://github.com/dotnet/docfx/issues/1254#issuecomment-294080535 * revert nonworking hack - Divide prep steps into two. * Changed ordering * Try to generate docs without the build.ps1 script * Try to generate docs without the build.ps1 script * Try to generate docs without the build.ps1 script * Try to remove the examine one, to test if that is the reason it fails on azure pipeline * Try to remove the sqlce one, to test if that is the reason it fails on azure pipeline * Reintroduce Examine and SqlCE docs, as these was not the reason it will not work on azure pipeline. * Test if azure wanna build the docs without explicit version * Fixed two malformed xml docs * hardcode version of docfx, to hopefully let it pass on azure pipeline * hardcode version of docfx, to hopefully let it pass on azure pipeline * Restructure azure pipeline yaml to have stages as areas instead of OS * Restructure azure pipeline yaml to have stages as areas instead of OS * yml restructure * yml restructure * yml restructure * Not hardcoding docfx as the old versions also fail on azure * Fixed Badly formed XML comments * moved condition from job to stage * split build and metadata * indentation * removed wrong char * Try to add more loging on azure pipeline * include less * include less projects * add one more project * More azure pipeline test * indentation * All except infrastructure * publish tasks * Fix link on logo * Extensions also included * Less links * re-introduced infrastructure to the list of projects for generate docfx for. * Add filter * Remove single warning for xmldocs * more logging? * skip some things from the metadata * test using other image * Test if exclude filter works * Test with more explict filters, allowing some docs from Infrastructure * binary search for the file that is the issue * binary search for the file that is the issue * binary search for the file that is the issue * Exclude more folders * Exclude more folders and files * Only exclude files in root of namespace? * more filter trials * more filter trials * add 2 nested folders * all cs files? * Remove test projects * Toc * Update build/azure-pipelines.yml * move display name element * Update build/azure-pipelines.yml Co-authored-by: Mole Co-authored-by: Mole --- build/azure-pipelines.yml | 556 ++++++++++-------- src/ApiDocs/docfx.filter.yml | 10 +- src/ApiDocs/docfx.json | 15 +- src/ApiDocs/index.md | 8 +- src/ApiDocs/toc.yml | 12 +- .../partials/navbar.tmpl.partial | 2 +- .../Models/Membership/EntityPermissionSet.cs | 2 +- .../Enrichers/HttpRequestIdEnricher.cs | 2 +- .../Enrichers/HttpRequestNumberEnricher.cs | 2 +- .../Enrichers/HttpSessionIdEnricher.cs | 6 +- .../Logging/Serilog/SerilogLogger.cs | 2 +- .../Logging/Viewer/ILogViewer.cs | 2 +- .../Repositories/IDocumentRepository.cs | 2 +- .../VirtualPageApplicationModelProvider.cs | 2 +- .../Controllers/IVirtualPageController.cs | 2 +- .../UmbracoVirtualPageFilterAttribute.cs | 2 +- 16 files changed, 339 insertions(+), 288 deletions(-) diff --git a/build/azure-pipelines.yml b/build/azure-pipelines.yml index 5537391bbf..a41d0f5b7f 100644 --- a/build/azure-pipelines.yml +++ b/build/azure-pipelines.yml @@ -1,277 +1,317 @@ -############################################################################# -## ASP.NET Core ## -## Build and test ASP.NET Core projects targeting .NET Core. ## -## Runs tests, creates NuGet packages: ## -## https://docs.microsoft.com/azure/devops/pipelines/languages/dotnet-core ## -############################################################################# - -# Variables & their default values variables: - buildConfiguration: 'Release' - SA_PASSWORD: UmbracoIntegration123! - + buildConfiguration: Release + SA_PASSWORD: UmbracoIntegration123! resources: - containers: - - container: mssql - image: mcr.microsoft.com/mssql/server:2017-latest - env: - ACCEPT_EULA: Y - SA_PASSWORD: $(SA_PASSWORD) - MSSQL_PID: Developer - ports: - - 1433:1433 - options: --name mssql - + containers: + - container: mssql + image: 'mcr.microsoft.com/mssql/server:2017-latest' + env: + ACCEPT_EULA: 'Y' + SA_PASSWORD: $(SA_PASSWORD) + MSSQL_PID: Developer + ports: + - '1433:1433' + options: '--name mssql' stages: -- stage: Linux - dependsOn: [] # this removes the implicit dependency on previous stage and causes this to run in parallel - jobs: + - stage: Unit_Tests + displayName: Unit Tests + dependsOn: [] + jobs: + - job: Linux_Unit_Tests + displayName: Linux + pool: + vmImage: ubuntu-latest + steps: + - task: UseDotNet@2 + displayName: Use .Net Core sdk 5.x + inputs: + version: 5.x + - task: DotNetCoreCLI@2 + displayName: dotnet test + inputs: + command: test + projects: '**/*.Tests.UnitTests.csproj' + - job: MacOS_Unit_Tests + displayName: Mac OS + pool: + vmImage: macOS-latest + steps: + - task: UseDotNet@2 + displayName: Use .Net Core sdk 5.x + inputs: + version: 5.x + - task: DotNetCoreCLI@2 + displayName: dotnet test + inputs: + command: test + projects: '**/*.Tests.UnitTests.csproj' + - job: Windows_Unit_Tests + displayName: Windows + pool: + vmImage: windows-latest + steps: + - task: UseDotNet@2 + displayName: Use .Net Core sdk 5.x + inputs: + version: 5.x + - task: DotNetCoreCLI@2 + displayName: dotnet test + inputs: + command: test + projects: '**/*.Tests.UnitTests.csproj' + - stage: Integration_Tests + displayName: Integration Tests + dependsOn: [] + jobs: + - job: Linux_Integration_Tests + services: + mssql: mssql + timeoutInMinutes: 120 + displayName: Linux + pool: + vmImage: ubuntu-latest + steps: + - task: UseDotNet@2 + displayName: Use .Net Core sdk 5.x + inputs: + version: 5.x + - task: DotNetCoreCLI@2 + displayName: dotnet test + inputs: + command: test + projects: '**/Umbraco.Tests.Integration.csproj' + env: + UmbracoIntegrationTestConnectionString: 'Server=localhost,1433;User Id=sa;Password=$(SA_PASSWORD);' + - job: Windows_Integration_Tests + timeoutInMinutes: 120 + displayName: Windows + pool: + vmImage: windows-latest + steps: + - task: UseDotNet@2 + displayName: Use .Net Core sdk 5.x + inputs: + version: 5.x + - powershell: sqllocaldb start mssqllocaldb + displayName: Start MSSQL LocalDb + - task: DotNetCoreCLI@2 + displayName: dotnet test + inputs: + command: test + projects: '**\Umbraco.Tests.Integration.csproj' + - stage: Artifacts + dependsOn: [] + jobs: + - job: Build_Artifacts + displayName: Build Artifacts + pool: + vmImage: windows-latest + steps: + - task: UseDotNet@2 + displayName: Use .Net Core sdk 5.x + inputs: + version: 5.x + - task: NuGetToolInstaller@1 + displayName: Use NuGet Latest + - task: NuGetCommand@2 + displayName: Restore NuGet Packages + inputs: + restoreSolution: '*\src\umbraco.sln' + feedsToUse: config + - task: PowerShell@1 + displayName: Update Version + condition: 'eq(variables[''Umbraco.IsReleaseBuild''], ''false'')' + inputs: + scriptType: inlineScript + inlineScript: > + Write-Host "Working folder: $pwd" - - job: Unit_Tests - displayName: 'Unit Tests' - pool: - vmImage: 'ubuntu-latest' - steps: + $ubuild = build/build.ps1 -get -continue - - task: UseDotNet@2 - displayName: 'Use .Net Core sdk 5.0.x' - inputs: - version: 5.0.x - - task: DotNetCoreCLI@2 - displayName: 'dotnet test' - inputs: - command: test - projects: '**/*.Tests.UnitTests.csproj' + $version = $ubuild.GetUmbracoVersion() - - job: Integration_Tests - services: - mssql: mssql - timeoutInMinutes: 120 - displayName: 'Integration Tests' - pool: - vmImage: 'ubuntu-latest' - steps: + if ($version.Comment -ne "") + { + # 8.0.0-beta.33.1234 + $continuous = "$($version.Semver).$(Build.BuildNumber)" + } + else + { + # 8.0.0-alpha.1234 + $continuous = "$($version.Release)-alpha.$(Build.BuildNumber)" + } + $ubuild.SetUmbracoVersion($continuous) - - task: UseDotNet@2 - displayName: 'Use .Net Core sdk 5.0.x' - inputs: - version: 5.0.x - - task: DotNetCoreCLI@2 - displayName: 'dotnet test' - inputs: - command: test - projects: '**/Umbraco.Tests.Integration.csproj' - env: - UmbracoIntegrationTestConnectionString: 'Server=localhost,1433;User Id=sa;Password=$(SA_PASSWORD);' + #Update the version in template also -- stage: MacOS - dependsOn: [] # this removes the implicit dependency on previous stage and causes this to run in parallel - jobs: + $templatePath = + 'build/templates/UmbracoSolution/.template.config/template.json' - - job: Unit_Tests - displayName: 'Unit Tests' - pool: - vmImage: 'macOS-latest' - steps: + $a = Get-Content $templatePath -raw | ConvertFrom-Json - - task: UseDotNet@2 - displayName: 'Use .Net Core sdk 5.0.x' - inputs: - version: 5.0.x + $a.symbols.version.defaultValue = $continuous - - task: DotNetCoreCLI@2 - displayName: 'dotnet test' - inputs: - command: test - projects: '**/*.Tests.UnitTests.csproj' + $a | ConvertTo-Json -depth 32| set-content $templatePath -- stage: Windows - dependsOn: [] # this removes the implicit dependency on previous stage and causes this to run in parallel - jobs: - - job: Unit_Tests - displayName: 'Unit Tests' - pool: - vmImage: 'windows-latest' - steps: + Write-Host "Building: $continuous" + - task: PowerShell@1 + displayName: Prepare Build + inputs: + scriptType: inlineScript + inlineScript: | + Write-Host "Working folder: $pwd" + $ubuild = build\build.ps1 -get - - task: UseDotNet@2 - displayName: 'Use .Net Core sdk 5.0.x' - inputs: - version: 5.0.x + $ubuild.PrepareBuild("vso") + - task: NodeTool@0 + displayName: Use Node 11.x + inputs: + versionSpec: 11.x + - task: Npm@1 + displayName: npm install + inputs: + workingDir: src\Umbraco.Web.UI.Client + verbose: false + - task: gulp@0 + displayName: gulp build + inputs: + gulpFile: src\Umbraco.Web.UI.Client\gulpfile.js + targets: build + workingDirectory: src\Umbraco.Web.UI.Client + publishJUnitResults: true + testResultsFiles: '**\TESTS-*.xml' + - task: PowerShell@1 + displayName: Prepare Packages & Zip + inputs: + scriptType: inlineScript + inlineScript: | + Write-Host "Working folder: $pwd" + $ubuild = build\build.ps1 -get -continue - - task: DotNetCoreCLI@2 - displayName: 'dotnet test' - inputs: - command: test - projects: '**\*.Tests.UnitTests.csproj' + $ubuild.CompileUmbraco() + $ubuild.PreparePackages() + $ubuild.PackageZip() + - task: CopyFiles@2 + displayName: Copy Zip Files to Staging + inputs: + SourceFolder: build.out + Contents: '*.zip' + TargetFolder: $(build.artifactstagingdirectory) + CleanTargetFolder: true + - task: PublishBuildArtifacts@1 + displayName: Publish Zip Files + inputs: + PathtoPublish: $(build.artifactstagingdirectory) + ArtifactName: zips + - task: PowerShell@1 + displayName: Verify & Package NuGet + inputs: + scriptType: inlineScript + inlineScript: | + Write-Host "Working folder: $pwd" + $ubuild = build\build.ps1 -get -continue - - job: Integration_Tests - timeoutInMinutes: 120 - displayName: 'Integration Tests' - pool: - vmImage: 'windows-latest' - steps: + $ubuild.VerifyNuGet() + $ubuild.PackageNuGet() + - task: CopyFiles@2 + displayName: Copy NuPkg Files to Staging + inputs: + SourceFolder: build.out + Contents: '*.nupkg' + TargetFolder: $(build.artifactstagingdirectory) + CleanTargetFolder: true + - task: PublishBuildArtifacts@1 + displayName: Publish NuPkg Files + inputs: + PathtoPublish: $(build.artifactstagingdirectory) + ArtifactName: nupkg + - task: CopyFiles@2 + displayName: Copy Log Files to Staging + inputs: + SourceFolder: build.tmp + Contents: '*.log' + TargetFolder: $(build.artifactstagingdirectory) + CleanTargetFolder: true + condition: succeededOrFailed() + - task: PublishBuildArtifacts@1 + displayName: Publish Log Files + inputs: + PathtoPublish: $(build.artifactstagingdirectory) + ArtifactName: logs + condition: succeededOrFailed() + - stage: Artifacts_Docs + displayName: 'Static Code Documentation' + dependsOn: [] + condition: 'ne(variables[''Umbraco.IsReleaseBuild''], ''false'')' + jobs: + - job: Generate_Docs_CSharp + timeoutInMinutes: 60 + displayName: Generate C# Docs + pool: + vmImage: windows-latest + steps: + - task: UseDotNet@2 + displayName: Use .Net Core sdk 5.x + inputs: + version: 5.x + - task: PowerShell@2 + displayName: 'Prep build tool - C# Docs' + inputs: + targetType: inline + script: | + choco install docfx -y + if ($lastexitcode -ne 0){ + throw ("Error installing DocFX") + } + docfx metadata --loglevel Verbose "$(Build.SourcesDirectory)\src\ApiDocs\docfx.json" + if ($lastexitcode -ne 0){ + throw ("Error generating docs.") + } + docfx build --loglevel Verbose "$(Build.SourcesDirectory)\src\ApiDocs\docfx.json" + if ($lastexitcode -ne 0){ + throw ("Error generating docs.") + } + errorActionPreference: continue + workingDirectory: build + - task: ArchiveFiles@2 + displayName: 'Zip C# Docs' + inputs: + rootFolderOrFile: $(Build.SourcesDirectory)\src\ApiDocs\_site + includeRootFolder: false + archiveType: zip + archiveFile: $(Build.ArtifactStagingDirectory)\docs\csharp-docs.zip + replaceExistingArchive: true + - task: PublishPipelineArtifact@1 + displayName: Publish to artifacts - C# Docs + inputs: + targetPath: $(Build.ArtifactStagingDirectory)\docs\csharp-docs.zip + artifact: docs-cs + publishLocation: pipeline - - task: UseDotNet@2 - displayName: 'Use .Net Core sdk 5.0.x' - inputs: - version: 5.0.x - - - powershell: 'sqllocaldb start mssqllocaldb' - displayName: 'Start MSSQL LocalDb' - - - task: DotNetCoreCLI@2 - displayName: 'dotnet test' - inputs: - command: test - projects: '**\Umbraco.Tests.Integration.csproj' - - - job: Build_Artifacts - displayName: 'Build Artifacts' - pool: - vmImage: 'windows-latest' - steps: - - - task: UseDotNet@2 - displayName: 'Use .Net Core sdk 5.0.x' - inputs: - version: 5.0.x - - - task: NuGetToolInstaller@1 - displayName: 'Use NuGet Latest' - - - task: NuGetCommand@2 - displayName: 'Restore NuGet Packages' - inputs: - restoreSolution: '*\src\umbraco.sln' - feedsToUse: config - - - task: PowerShell@1 - displayName: 'Update Version' - condition: eq(variables['Umbraco.IsReleaseBuild'], 'false') - inputs: - scriptType: inlineScript - inlineScript: | - Write-Host "Working folder: $pwd" - $ubuild = build/build.ps1 -get -continue - - $version = $ubuild.GetUmbracoVersion() - if ($version.Comment -ne "") - { - # 8.0.0-beta.33.1234 - $continuous = "$($version.Semver).$(Build.BuildNumber)" - } - else - { - # 8.0.0-alpha.1234 - $continuous = "$($version.Release)-alpha.$(Build.BuildNumber)" - } - $ubuild.SetUmbracoVersion($continuous) - - #Update the version in template also - $templatePath = 'build/templates/UmbracoSolution/.template.config/template.json' - $a = Get-Content $templatePath -raw | ConvertFrom-Json - $a.symbols.version.defaultValue = $continuous - $a | ConvertTo-Json -depth 32| set-content $templatePath - - Write-Host "Building: $continuous" - - - task: PowerShell@1 - displayName: 'Prepare Build' - inputs: - scriptType: inlineScript - inlineScript: | - Write-Host "Working folder: $pwd" - $ubuild = build\build.ps1 -get - - $ubuild.PrepareBuild("vso") - - - task: NodeTool@0 - displayName: 'Use Node 11.x' - inputs: - versionSpec: 11.x - - - task: Npm@1 - displayName: 'npm install' - inputs: - workingDir: src\Umbraco.Web.UI.Client - verbose: false - - - task: gulp@0 - displayName: 'gulp build' - inputs: - gulpFile: src\Umbraco.Web.UI.Client\gulpfile.js - targets: build - workingDirectory: src\Umbraco.Web.UI.Client - publishJUnitResults: true - testResultsFiles: '**\TESTS-*.xml' - - - task: PowerShell@1 - displayName: 'Prepare Packages & Zip' - inputs: - scriptType: inlineScript - inlineScript: | - Write-Host "Working folder: $pwd" - $ubuild = build\build.ps1 -get -continue - - $ubuild.CompileUmbraco() - $ubuild.PreparePackages() - $ubuild.PackageZip() - - - task: CopyFiles@2 - displayName: 'Copy Zip Files to Staging' - inputs: - SourceFolder: build.out - Contents: '*.zip' - TargetFolder: '$(build.artifactstagingdirectory)' - CleanTargetFolder: true - - - task: PublishBuildArtifacts@1 - displayName: 'Publish Zip Files' - inputs: - PathtoPublish: '$(build.artifactstagingdirectory)' - ArtifactName: zips - - - task: PowerShell@1 - displayName: 'Verify & Package NuGet' - inputs: - scriptType: inlineScript - inlineScript: | - Write-Host "Working folder: $pwd" - $ubuild = build\build.ps1 -get -continue - - $ubuild.VerifyNuGet() - $ubuild.PackageNuGet() - - - task: CopyFiles@2 - displayName: 'Copy NuPkg Files to Staging' - inputs: - SourceFolder: build.out - Contents: '*.nupkg' - TargetFolder: '$(build.artifactstagingdirectory)' - CleanTargetFolder: true - - - task: PublishBuildArtifacts@1 - displayName: 'Publish NuPkg Files' - inputs: - PathtoPublish: '$(build.artifactstagingdirectory)' - ArtifactName: nupkg - - - task: CopyFiles@2 - displayName: 'Copy Log Files to Staging' - inputs: - SourceFolder: build.tmp - Contents: '*.log' - TargetFolder: '$(build.artifactstagingdirectory)' - CleanTargetFolder: true - condition: succeededOrFailed() - - - task: PublishBuildArtifacts@1 - displayName: 'Publish Log Files' - inputs: - PathtoPublish: '$(build.artifactstagingdirectory)' - ArtifactName: logs - condition: succeededOrFailed() + - job: Generate_Docs_JS + timeoutInMinutes: 60 + displayName: Generate JS Docs + pool: + vmImage: windows-latest + steps: + - task: PowerShell@2 + displayName: Prep build tool - JS Docs + inputs: + targetType: inline + script: | + $uenv=./build.ps1 -get -doc + $uenv.SandboxNode() + $uenv.CompileBelle() + $uenv.PrepareAngularDocs() + $uenv.RestoreNode() + errorActionPreference: continue + workingDirectory: build + - task: PublishPipelineArtifact@1 + displayName: Publish to artifacts - JS Docs + inputs: + targetPath: $(Build.Repository.LocalPath)\build.out\ + artifact: docs + publishLocation: pipeline diff --git a/src/ApiDocs/docfx.filter.yml b/src/ApiDocs/docfx.filter.yml index e96fbaafff..db82957d00 100644 --- a/src/ApiDocs/docfx.filter.yml +++ b/src/ApiDocs/docfx.filter.yml @@ -1,10 +1,8 @@ apiRules: - include: - uidRegex: ^Umbraco\.Core - - exclude: - uidRegex: ^umbraco\.Web\.org + uidRegex: ^Umbraco\.Cms - include: - uidRegex: ^Umbraco\.Web + uidRegex: ^Umbraco\.Extensions - exclude: hasAttribute: uid: System.ComponentModel.EditorBrowsableAttribute @@ -13,6 +11,6 @@ apiRules: - exclude: uidRegex: ^umbraco\. - exclude: - uidRegex: ^CookComputing\. + uidRegex: ^CookComputing\. - exclude: - uidRegex: ^.*$ \ No newline at end of file + uidRegex: ^.*$ diff --git a/src/ApiDocs/docfx.json b/src/ApiDocs/docfx.json index 76677d45d5..2e9d9c0836 100644 --- a/src/ApiDocs/docfx.json +++ b/src/ApiDocs/docfx.json @@ -2,15 +2,20 @@ "metadata": [ { "src": [ - { + { "src": "../", "files": [ - "Umbraco.Core/Umbraco.Core.csproj", - "Umbraco.Web/Umbraco.Web.csproj" + "**/*.csproj", + "**/Umbraco.Infrastructure/**/*.cs" ], "exclude": [ "**/obj/**", - "**/bin/**" + "**/bin/**", + "**/Umbraco.Web.csproj", + "**/Umbraco.Infrastructure.csproj", + "**/Umbraco.Web.UI.csproj", + "**/Umbraco.Web.UI.Netcore.csproj", + "**/**.Test**/*.csproj" ] } ], @@ -53,7 +58,7 @@ "_enableSearch": true, "_disableContribution": false }, - "dest": "../../build.tmp/_site", + "dest": "_site", "template": [ "default", "umbracotemplate" ] diff --git a/src/ApiDocs/index.md b/src/ApiDocs/index.md index b90b816312..2de11c438a 100644 --- a/src/ApiDocs/index.md +++ b/src/ApiDocs/index.md @@ -3,5 +3,9 @@ ## Quick Links: -### [Umbraco.Core](api/Umbraco.Core.html) docs -### [Umbraco.Web](api/Umbraco.Web.html) docs +### [Core](api/Umbraco.Cms.Core.html) docs +### [Infrastructure](api/Umbraco.Cms.Infrastructure.html) docs +### [Web](api/Umbraco.Cms.Web.Common.html) docs +### [Extensions](api/Umbraco.Extensions.html) docs + + diff --git a/src/ApiDocs/toc.yml b/src/ApiDocs/toc.yml index 23e2f3b8e1..8e9fc8b2c2 100644 --- a/src/ApiDocs/toc.yml +++ b/src/ApiDocs/toc.yml @@ -1,5 +1,9 @@ +- name: Core + href: api/Umbraco.Cms.Core.html +- name: Infrastructure + href: api/Umbraco.Cms.Infrastructure.html +- name: Web + href: api/Umbraco.Cms.Web.Common.html +- name: Extensions + href: api/Umbraco.Extensions.html -- name: Umbraco.Core Documentation - href: https://our.umbraco.com/apidocs/csharp/api/Umbraco.Core.html -- name: Umbraco.Web Documentation - href: https://our.umbraco.com/apidocs/csharp/api/Umbraco.Web.html \ No newline at end of file diff --git a/src/ApiDocs/umbracotemplate/partials/navbar.tmpl.partial b/src/ApiDocs/umbracotemplate/partials/navbar.tmpl.partial index e9ee0af1c7..e221e75c7c 100644 --- a/src/ApiDocs/umbracotemplate/partials/navbar.tmpl.partial +++ b/src/ApiDocs/umbracotemplate/partials/navbar.tmpl.partial @@ -9,7 +9,7 @@ - +