diff --git a/.editorconfig b/.editorconfig index 28c31de9d7f2..58fd7faad06d 100644 --- a/.editorconfig +++ b/.editorconfig @@ -23,6 +23,10 @@ indent_size = 2 [*.md] indent_style = space +indent_size = 2 +trim_trailing_whitespace = true + +[*.{csproj,props,targets}] [*.cs] # http://kent-boogaart.com/blog/editorconfig-reference-for-c-developers#csharp_indent_block_contents diff --git a/build/cSpell.json b/build/cSpell.json index d9ca18283f29..57fa882a1028 100644 --- a/build/cSpell.json +++ b/build/cSpell.json @@ -2,268 +2,272 @@ "version": "0.2", "language": "en", "words": [ - "Avalonia", - "ambiently", - "appmanifest", - "binlog", - "Blazor", - "blockquotes", - "Bootstrapper", - "brotli", - "browsersync", - "bytecode", - "Callout", - "chatops", - "codebases", - "Codespace", - "Codespaces", - "Contoso", - "crossruntime", - "Cupertino", - "customizability", - "databinding", - "datacontext", - "datagrid", - "decompile", - "devs", - "dbus", - "Dismissable", - "dmgbuild", - "Docfx", - "ellipsize", - "Entra", - "Expando", - "flyouts", - "Framebuffer", - "fullname", - "Gamepad", - "gamepads", - "Geolocation", - "globbing", - "Grial", - "Grayscale", - "Gyrometer", - "Hanja", - "hectopascals", - "HoloLens", - "howto", - "hotreload", - "hotswap", - "Inlines", - "keychain", - "laggy", - "layouter", - "layouting", - "Listview", - "listviewbase", - "Linq", - "LLRM", - "lookless", - "mergeable", - "Microcharts", - "MSAL", - "msbuild", - "MVUX", - "MVVM", - "MSIX", - "NETSDK", - "NBGV", - "netstandard", - "neumorphic", - "oidc", - "Omnisharp", - "overscroll", - "Packt", - "parameterless", - "pickable", - "Pluralsight", - "POSIX", - "reentrantly", - "Resizetizer", - "resw", - "roadmap", - "retargeting", - "sandboxed", - "Segoe", - "Silverlight", - "signalr", - "Skia", - "skiasharp", - "Snapcraft", - "Storyboarded", - "struct", - "Syncfusion", - "Telerik", - "templatable", - "templating", - "themeresource", - "timespan", - "Tizen", - "TLDR", - "toolkits", - "triaging", - "UI's", - "unmanaged", - "Uno's", - "unoplatform", - "upvote", - "UWP's", - "VSIX", - "walkthrough", - "WEBASSEMBLY", - "webservices", - "webapps", - "Haptics", - "autoplay", - "Xcodes", - "Raygun", - "waitlist" + "ambiently", + "appmanifest", + "autoplay", + "Avalonia", + "binlog", + "Blazor", + "blockquotes", + "Bootstrapper", + "brotli", + "browsersync", + "bytecode", + "Callout", + "chatops", + "codebases", + "Codespace", + "Codespaces", + "Contoso", + "crossruntime", + "Cupertino", + "customizability", + "databinding", + "datacontext", + "datagrid", + "dbus", + "decompile", + "devs", + "Dismissable", + "dmgbuild", + "Docfx", + "dotnet", + "ellipsize", + "Entra", + "Expando", + "figma", + "flyouts", + "Framebuffer", + "fullname", + "Gamepad", + "gamepads", + "Geolocation", + "globbing", + "Grayscale", + "Grial", + "Gyrometer", + "Hanja", + "Haptics", + "hectopascals", + "HoloLens", + "hotreload", + "hotswap", + "howto", + "Inlines", + "keychain", + "laggy", + "layouter", + "layouting", + "Linq", + "Listview", + "listviewbase", + "LLRM", + "lookless", + "mergeable", + "Microcharts", + "MSAL", + "msbuild", + "MSIX", + "MVUX", + "MVVM", + "NBGV", + "NETSDK", + "netstandard", + "neumorphic", + "oidc", + "OmniSharp", + "overscroll", + "Packt", + "parameterless", + "pickable", + "Pluralsight", + "POSIX", + "Raygun", + "reentrantly", + "resizetizer", + "Resizetizer", + "resw", + "retargeting", + "roadmap", + "sandboxed", + "Segoe", + "signalr", + "Silverlight", + "Skia", + "skiasharp", + "Snapcraft", + "storyboarded", + "Storyboarded", + "struct", + "Syncfusion", + "Telerik", + "templatable", + "templating", + "themeresource", + "timespan", + "Tizen", + "TLDR", + "toolkits", + "triaging", + "UI's", + "unmanaged", + "Uno's", + "unoplatform", + "upvote", + "UWP's", + "VSIX", + "waitlist", + "walkthrough", + "webapps", + "WEBASSEMBLY", + "webservices", + "Xcodes" ], "ignoreWords": [ - "ADAL", - "AEHD", - "appsettings", - "applicationdata", - "applicationmodel", - "Authenticode", - "automagically", - "bluetoothdevice", - "browserwasm", - "commandbar", - "CLSID", - "datatransfer", - "Divio's", - "emcc", - "emscripten", - "Flatpickr", - "Giesel", - "GPIO", - "hdpi", - "Headered", - "Hoefling", - "HRESULT", - "IDBFS", - "Infragistics", - "Jiterpreter", - "jonathanpeppers's", - "Krueger", - "libgtk", - "lightsensor", - "Liu's", - "macios", - "Matteo", - "McCaffrey", - "mdpi", - "Mergify", - "mlaunch", - "netstd", - "nventive", - "odel", - "pdate", - "progressring", - "pwsh", - "Ronica", - "Serilog", - "Sideloading", - "sideload", - "Singh", - "slnf", - "startscreen", - "Stetho", - "Talkin", - "timeentry", - "UADO", - "Udemy", - "UNOB", - "UNOX", - "UVSC", - "uitest", - "upri", - "userprofile", - "winui", - "xhdpi", - "xxhdpi", - "xxxhdpi", - "illinker", - "Onoh", - "Findlay", - "Logpoints", - "addin", - "Yowza", - "unpackaged", - "GNSS", - "vibrationdevice", - "viewmanagement", - "winappsdk", - "notimplemented", - "winrt", - "winapp", - "wapproj's", - "xamlmerge", - "xbind", - "xcprivacy", - "jlaban", - "sasakrsmanovic", - "maccatalyst", - "settingscard", - "storecontext", - "tvos", - "appleuikit", - "uikit", - "settingscard" + "ADAL", + "AEHD", + "appsettings", + "applicationdata", + "applicationmodel", + "Authenticode", + "automagically", + "bluetoothdevice", + "browserwasm", + "commandbar", + "CLSID", + "datatransfer", + "Divio's", + "emcc", + "emscripten", + "Flatpickr", + "Giesel", + "GPIO", + "hdpi", + "Headered", + "Hoefling", + "HRESULT", + "IDBFS", + "Infragistics", + "Jiterpreter", + "jonathanpeppers's", + "Krueger", + "libgtk", + "lightsensor", + "Liu's", + "macios", + "Matteo", + "McCaffrey", + "mdpi", + "Mergify", + "mlaunch", + "netstd", + "nventive", + "odel", + "pdate", + "progressring", + "pwsh", + "Ronica", + "Serilog", + "Sideloading", + "sideload", + "Singh", + "slnf", + "startscreen", + "Stetho", + "Talkin", + "timeentry", + "UADO", + "Udemy", + "UNOB", + "UNOX", + "UVSC", + "uitest", + "upri", + "userprofile", + "winui", + "xhdpi", + "xxhdpi", + "xxxhdpi", + "illinker", + "Onoh", + "Findlay", + "Logpoints", + "addin", + "Yowza", + "unpackaged", + "GNSS", + "vibrationdevice", + "viewmanagement", + "winappsdk", + "notimplemented", + "winrt", + "winapp", + "wapproj's", + "xamlmerge", + "xbind", + "xcprivacy", + "jlaban", + "sasakrsmanovic", + "maccatalyst", + "settingscard", + "storecontext", + "tvos", + "appleuikit", + "uikit", + "settingscard" ], "patterns": [ - { - "name": "Markdown uid", - "pattern": "^(?=uid:).*$", - "description": "" - }, - { - "name": "Markdown links", - "pattern": "\\((.*)\\)", - "description": "" - }, - { - "name": "Markdown code blocks", - "pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx", - "description": "Taken from the cSpell example at https://cspell.org/configuration/patterns/#verbose-regular-expressions" - }, - { - "name": "Inline code blocks", - "pattern": "\\`([^\\`\\r\\n]+?)\\`", - "description": "https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex" - }, - { - "name": "Link contents", - "pattern": "\\", - "description": "" - }, - { - "name": "Snippet references", - "pattern": "-- snippet:(.*)", - "description": "" - }, - { - "name": "Snippet references 2", - "pattern": "\\<\\[sample:(.*)", - "description": "another kind of snippet reference" - }, - { - "name": "Multi-line code blocks", - "pattern": "/^\\s*```[\\s\\S]*?^\\s*```/gm" - } + { + "name": "Markdown uid", + "pattern": "^(?=uid:).*$", + "description": "" + }, + { + "name": "Markdown links", + "pattern": "\\((.*)\\)", + "description": "" + }, + { + "name": "Markdown code blocks", + "pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx", + "description": "Taken from the cSpell example at https://cspell.org/configuration/patterns/#verbose-regular-expressions" + }, + { + "name": "Inline code blocks", + "pattern": "\\`([^\\`\\r\\n]+?)\\`", + "description": "https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex" + }, + { + "name": "Link contents", + "pattern": "\\", + "description": "" + }, + { + "name": "Snippet references", + "pattern": "-- snippet:(.*)", + "description": "" + }, + { + "name": "Snippet references 2", + "pattern": "\\<\\[sample:(.*)", + "description": "another kind of snippet reference" + }, + { + "name": "Multi-line code blocks", + "pattern": "/^\\s*```[\\s\\S]*?^\\s*```/gm" + } ], "ignoreRegExpList": [ - "Markdown uid", - "Markdown links", - "Markdown code blocks", - "Inline code blocks", - "Link contents", - "Snippet references", - "Snippet references 2", - "Multi-line code blocks" + "Markdown uid", + "Markdown links", + "Markdown code blocks", + "Inline code blocks", + "Link contents", + "Snippet references", + "Snippet references 2", + "Multi-line code blocks" ], "ignorePaths": [ - "../doc/index.md" + "../doc/index.md" ] } diff --git a/doc/.feature-template-uno-only.md b/doc/.feature-template-uno-only.md index d2d603f01d49..38a363eed5f9 100644 --- a/doc/.feature-template-uno-only.md +++ b/doc/.feature-template-uno-only.md @@ -1,4 +1,6 @@ - +--- +uid: Uno.Doc-Templates.Feature.Uno-only +--- # YourFeature @@ -18,7 +20,7 @@ -| Feature | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) | +| Feature | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) | |---------------|-------|-------|-------|-------|-------|-------|-| | Feature1 | ✔ | ✔/✖ (choose appropriate) | ? (fill in) | ? | ? | ? | ? | | Feature2... | ✔ | ? | ? | ? | ? | ? | ? | diff --git a/doc/.feature-template.md b/doc/.feature-template.md index 391f34eebbed..ef56ebe72c90 100644 --- a/doc/.feature-template.md +++ b/doc/.feature-template.md @@ -1,4 +1,6 @@ - +--- +uid: Uno.Doc-Templates.Feature.Uno-Specifics +--- # YourFeature @@ -12,7 +14,7 @@ ## Supported features -| Feature | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) | +| Feature | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) | |---------------|-------|-------|-------|-------|-------|-------|-| | Feature1 | ✔ | ✔/✖ (choose appropriate) | ? (fill in) | ? | ? | ? | ? | | Feature2... | ✔ | ? | ? | ? | ? | ? | ? | diff --git a/doc/.howto-template.md b/doc/.howto-template.md index 91c108163d79..29195a7e1bbd 100644 --- a/doc/.howto-template.md +++ b/doc/.howto-template.md @@ -1,3 +1,7 @@ +--- +uid: Uno.Doc-Templates.How-To +--- + # How to [complete TaskX] @@ -38,16 +42,6 @@ > Use `dotnet --version` from the terminal to get the version installed. -### [Visual Studio for Mac](#tab/tabid-vsmac) - -* [**Visual Studio for Mac 8.8**](https://visualstudio.microsoft.com/vs/mac/) -* [**Xcode**](https://apps.apple.com/us/app/xcode/id497799835?mt=12) 10.0 or higher -* An [**Apple ID**](https://support.apple.com/HT204316) -* **.NET Core SDK** - * [.NET Core 3.1 SDK](https://dotnet.microsoft.com/download/dotnet-core/3.1) (**version 3.1.8 (SDK 3.1.402)** or later) - * [.NET Core 5.0 SDK](https://dotnet.microsoft.com/download/dotnet-core/5.0) (**version 5.0 (SDK 5.0.100)** or later) -* [**GTK+3**](https://formulae.brew.sh/formula/gtk+3) for running the Skia/GTK projects - ### [JetBrains Rider](#tab/tabid-rider) * [**Rider Version 2020.2+**](https://www.jetbrains.com/rider/download/) diff --git a/doc/articles/Assets/check-toc-find-toc-additions-file.gif b/doc/articles/Assets/check-toc-find-toc-additions-file.gif new file mode 100644 index 000000000000..7d1cb30a11a9 Binary files /dev/null and b/doc/articles/Assets/check-toc-find-toc-additions-file.gif differ diff --git a/doc/articles/check-toc-utilities/Get-IrrelevantThings.ps1 b/doc/articles/check-toc-utilities/Get-IrrelevantThings.ps1 new file mode 100644 index 000000000000..fa55ed52ec6b --- /dev/null +++ b/doc/articles/check-toc-utilities/Get-IrrelevantThings.ps1 @@ -0,0 +1,6 @@ +function Get-IrrelevantThings { # This function is not used in the script, only for testing + param ( + + ) + +} \ No newline at end of file diff --git a/doc/articles/check-toc-utilities/Get-MarkdownHeaders.Tests.ps1 b/doc/articles/check-toc-utilities/Get-MarkdownHeaders.Tests.ps1 new file mode 100644 index 000000000000..d2b4efba82ce --- /dev/null +++ b/doc/articles/check-toc-utilities/Get-MarkdownHeaders.Tests.ps1 @@ -0,0 +1,79 @@ +# Import the function to test +# dot source does not always work when using with Invoke-Pester -Output Detailed .\Get-MarkdownHeader.Test.ps1 +# so run . .\Get-MarkdownHeader.ps1 manually before. +BeforeAll { + . $PSCommandPath.Replace('.Tests.ps1','.ps1') +} + +Describe 'Get-MarkdownHeader' { + It 'Extracts the first valid Markdown header' { + # Arrange + $lines = @( + '---', + #'title: Example Title', # TODO: Uncomment this line if the title is transferred correctly as header in the future from Docfx + '---', + '', + '', + '# Header 1', + 'Some content', + 'title: Example Content with title prefix' + ) + + # Act + $header = Get-MarkdownHeader -Lines $lines -Verbose + + # Assert + $header | Should -Be 'Header 1' + } + It 'Extracts a header with multiple trailing #' { + # Arrange + $lines = @( + '## Header 2 ##', + 'Some content' + ) + + # Act + $header = Get-MarkdownHeader -Lines $lines -Verbose + + # Assert + $header | Should -Be 'Header 2' + } + # TODO: Uncomment this Test if the title is transferred correctly as header in the future from Docfx + # It 'Returns the title if no Markdown header is found' { + # # Arrange + # $lines = @( + # '---', + # 'title: Example Title', + # '---', + # '', + # '' + # ) + + # # Act + # $header = Get-MarkdownHeader -Lines $lines -Verbose + + # # Assert + # $header | Should -Be 'Example Title' + # } + + It 'Returns null if no header or title is found' { + # Arrange + $lines = @( + '---', + '', + '' + ) + + # Act + $header = Get-MarkdownHeader -Lines $lines -Verbose + + # Assert + $header | Should -Be $null + } +} \ No newline at end of file diff --git a/doc/articles/check-toc-utilities/Get-MarkdownHeaders.ps1 b/doc/articles/check-toc-utilities/Get-MarkdownHeaders.ps1 new file mode 100644 index 000000000000..c36f1f474cc7 --- /dev/null +++ b/doc/articles/check-toc-utilities/Get-MarkdownHeaders.ps1 @@ -0,0 +1,37 @@ +function Get-MarkdownHeader { + [CmdletBinding()] + param ( + [string[]]$Lines + ) + + $inComment = $false + # Write-Verbose "Processing lines: $Lines" + + # Find the first non-comment line that starts with 1-6 # characters + foreach ($line in $Lines) { + # Write-Verbose "Checking line: $line" + if ($line -match '') { $inComment = $false } + } + + # TODO: Uncomment the following code if at any point, the title is transferred as header in Docfx output + + ## If no header is found, return the first line that starts with 'title:' + # foreach ($line in $Lines) { + ## Write-Verbose "Checking for title in line: $line" + # if ($line -match '^title:\s*(.+)') { + ## Write-Verbose "Matched title: $matches[1]" + # return $matches[1].Trim() + # } + #} + + # If no header is found, return $null + # Write-Verbose "No header or title found" + return $null +} diff --git a/doc/articles/check-toc-utilities/Get-UnlinkedFiles.Tests.ps1 b/doc/articles/check-toc-utilities/Get-UnlinkedFiles.Tests.ps1 new file mode 100644 index 000000000000..06e3be7d0a07 --- /dev/null +++ b/doc/articles/check-toc-utilities/Get-UnlinkedFiles.Tests.ps1 @@ -0,0 +1,88 @@ +# Import the function to test +BeforeAll { + . $PSCommandPath.Replace('.Tests.ps1','.ps1') +} + +Describe "Get-UnlinkedFiles" { + It "1. Returns unlinked files not in TOC or expected unlinked list" { + # Arrange + $allMdFiles = @("file1.md", "file2.md", "file3.md") + $allMdLinks = @("file1.md") + $expectedUnlinked = @("file3.md") + $allXrefLinksInToc = @("uid: My.Mocked.UID") + + # Mock file content for UID extraction + Mock -CommandName Get-Content -MockWith { + Write-Host "Mocking Get-Content for $($args[0])" + if ($args[0] -eq "file2.md") { "uid: My.Mocked.UID" } + else { "" } + } + + # Act + $result = Get-UnlinkedFiles -allMdFiles $allMdFiles -allMdLinks $allMdLinks -expectedUnlinked $expectedUnlinked -allXrefLinksInToc $allXrefLinksInToc + + # Assert + $result | Should -Be @("file2.md") + } + + It "2. Returns empty array if all files are linked or expected unlinked" { + # Arrange + $allMdFiles = @("file1.md", "file2.md") + $allMdLinks = @("file1.md", "file2.md") + $expectedUnlinked = @() + $allXrefLinksInToc = @("uid: My.Mocked.UID", "uid: My.Other.Mocked.Uid") + + # Mock file content for UID extraction + Mock -CommandName Get-Content -MockWith { + if ($args[0] -eq "file2.md") { "uid: My.Mocked.UID" } + else { "" } + } + + # Act + $result = Get-UnlinkedFiles -allMdFiles $allMdFiles -allMdLinks $allMdLinks -expectedUnlinked $expectedUnlinked -allXrefLinksInToc $allXrefLinksInToc + + # Assert + $result | Should -Be @() + } + + It "3. Handles files with no UID gracefully" { + # Arrange + $allMdFiles = @("file1.md", "file2.md") + $allMdLinks = @("file1.md") + $expectedUnlinked = @() + $allXrefLinksInToc = @("uid: Some.Uid") + + # Mock file content for UID extraction + Mock -CommandName Get-Content -MockWith { + if ($args[0] -eq "file2.md") { "" } + else { "" } + } + + # Act + $result = Get-UnlinkedFiles -allMdFiles $allMdFiles -allMdLinks $allMdLinks -expectedUnlinked $expectedUnlinked -allXrefLinksInToc $allXrefLinksInToc + + # Assert + $result | Should -Be @("file2.md") + } + + It "4. Identifies multiple unlinked files correctly"{ + # Test Input + $allMdFiles = @("file1.md", "file2.md", "file3.md") + $allMdLinks = @("file1.md") + $expectedUnlinked = @("file3.md") + $allXrefLinksInToc = @("uid1") + + # Mock Get-Content for testing + Mock -CommandName Get-Content -MockWith { + if ($args[0] -eq "file2.md") { "uid: uid2" } + elseif ($args[0] -eq "file3.md") { "" } + else { "" } + } + + # Run the function + $result = Get-UnlinkedFiles -allMdFiles $allMdFiles -allMdLinks $allMdLinks -expectedUnlinked $expectedUnlinked -allXrefLinksInToc $allXrefLinksInToc -Verbose + + # Output the result + Write-Host "Unlinked Files: $($result -join ', ')" + } +} \ No newline at end of file diff --git a/doc/articles/check-toc-utilities/Get-UnlinkedFiles.ps1 b/doc/articles/check-toc-utilities/Get-UnlinkedFiles.ps1 new file mode 100644 index 000000000000..7d97d56f47fd --- /dev/null +++ b/doc/articles/check-toc-utilities/Get-UnlinkedFiles.ps1 @@ -0,0 +1,41 @@ +function Get-UnlinkedFiles { + [CmdletBinding()] + param ( + [string[]]$allMdFiles, + [string[]]$allMdLinks, + [string[]]$expectedUnlinked, + [string[]]$allXrefLinksInToc + ) + + Write-Verbose 'Searching for unlinked md files that are not listed in TOC' + Write-Verbose "All Markdown Files: $($allMdFiles -join ', ')" + Write-Verbose "All Markdown Links: $($allMdLinks -join ', ')" + Write-Verbose "Expected Unlinked Files: $($expectedUnlinked -join ', ')" + Write-Verbose "All Xref Links in TOC: $($allXrefLinksInToc -join ', ')" + + $allMdFiles | + Where-Object { + -not ($allMdLinks -contains $_) -and + -not ($expectedUnlinked -contains $_) + } | + ForEach-Object { + $file = $_ + Write-Verbose "Processing file: $file" + + $uid = Get-Content $file -TotalCount 3 | + Where-Object { $_ -match 'uid:\s*(\S+)' } | + ForEach-Object { $matches[1] } + Write-Verbose "Extracted UID: $uid" + + if (-not $uid) { + Write-Verbose "No UID found in $file" + $file # Return the file if no UID is found + } elseif ($allXrefLinksInToc -notcontains $uid) { + Write-Verbose "UID $uid found in $file, but not in TOC" + $file # Return the file if the UID is not in the TOC + } else { + Write-Verbose "File $file is referred by $uid in TOC" + } + } + Write-Verbose 'Done!' +} \ No newline at end of file diff --git a/doc/articles/check-toc-utilities/Guide.md b/doc/articles/check-toc-utilities/Guide.md new file mode 100644 index 000000000000..40d556baf1bc --- /dev/null +++ b/doc/articles/check-toc-utilities/Guide.md @@ -0,0 +1,80 @@ +--- +uid: Uno.Contributing.check-toc.Guide +--- + +# How-To: Using the Toc Checker script + +This guide is for contributors working with the Uno documentation who want to verify the structure and consistency of the DocFX table of contents (TOC). The `check_toc.ps1` script identifies broken or missing links and helps ensure all Markdown articles are properly referenced in `toc.yml`. + +> [!TIP] +> The complete source code that goes along with this guide is available in the Uno repository – see the script at [`check_toc`](../check_toc.ps1). + +## Prerequisites + +- Any Uno Platform supported IDE + +### PowerShell Environment + +- Windows PowerShell 5.1 or PowerShell Core 7+ +- Local clone of the Uno documentation repository +- Write access to the `doc/articles` directory to generate temporary output + +--- + +> [!TIP] +> For a general overview of the script and its purpose, see the [TOC Checker Overview](xref:Uno.Contributing.check-toc.Overview). + +## Step 1 – Open PowerShell + +Open a terminal and navigate to the root of your Uno clone. + +## Step 2 – Navigate to the `articles` Directory + +The script must be executed from within the folder containing the `toc.yml` file. + +```powershell +cd doc/articles +``` + +> [!IMPORTANT] +> Relative paths are resolved from this directory. Executing from elsewhere will yield incorrect results. + +## Step 3 – Run the Script + +```powershell +& .\check_toc.ps1 +``` + +For verbose output: + +```powershell +& .\check_toc.ps1 -Verbose +``` + +## Step 4 – Review the Output + +- Console output will show broken links and unlinked files. +- A new file `toc_additions.yml.tmp` will be created in the current directory. + +Open this file to view `- name:` and `href:` entries that should be added to `toc.yml` in the **appropriate** category. + +## Troubleshooting + +- If nothing is reported, verify that the script was executed in the correct directory. +- If `toc_additions.yml.tmp` is missing, check for file permission issues. + + > [!NOTE] + > Visual Studio 2022 does not show the generated file by default. + > To open it, see these Steps: + > + > ![check-toc-find-toc-additions](..\Assets\check-toc-find-toc-additions-file.gif) + +## Related Pages + +- [TOC Checker Script Overview](xref:Uno.Contributing.check-toc.Overview) +- [Utility Functions](xref:Uno.Contributing.check-toc.Utilities) +- [Contributing Guidelines](xref:Uno.Contributing.DocFx) + +--- + +[!INCLUDE [getting-help](xref:Uno.Development.GettingHelp)] diff --git a/doc/articles/check-toc-utilities/Import-TocCheckerUtils.Tests.ps1 b/doc/articles/check-toc-utilities/Import-TocCheckerUtils.Tests.ps1 new file mode 100644 index 000000000000..db2673ea1983 --- /dev/null +++ b/doc/articles/check-toc-utilities/Import-TocCheckerUtils.Tests.ps1 @@ -0,0 +1,88 @@ +Describe "Import-TocCheckerUtils.ps1 Dot-Sourcing Functionality" { + # Import the function to test + BeforeAll { + . $PSCommandPath.Replace('.Tests.ps1','.ps1') + } + + It "should dot-source all .ps1 scripts in the folder except itself, excluded files and test scripts" { + # Arrange + $utilsFolder = $PSScriptRoot + $testFileName = $MyInvocation.MyCommand.Path # TODO: Fit to docs for using this correctly + $excludeFiles = @('Get-IrrelevantThings.ps1', 'Import-TocCheckerUtils.ps1', $testFileName) + + # Get all utility script files to be dot-sourced (excluding test and irrelevant ones) + $allPs1Files = Get-ChildItem -Path $utilsFolder -Filter *.ps1 | Where-Object { + $_.Name -notin $excludeFiles -and + $_.Name -notmatch '\.Test\.ps1$' + } + + Write-Host "PS1 Files to be dot-sourced:" + $allPs1Files | ForEach-Object { Write-Host $_.FullName } + + # Act - Call the dot-sourcing function + Import-TocCheckerUtils -UtilsFolder $utilsFolder -ExcludeFiles $excludeFiles + + # Capture all functions with source info + $dotSourcedFunctions = Get-Command -CommandType Function | Where-Object { + $_.ScriptBlock.File -like "$utilsFolder\*" + } + + # Extract names and normalize casing + $newFunctionNames = $dotSourcedFunctions | + Select-Object -ExpandProperty Name | + ForEach-Object { $_.ToLowerInvariant() } + + Write-Verbose ("Newly loaded functions:`n - " + ($newFunctionNames -join "`n - ")) + + # Assert - Each file must have at least one declared function that is now available + foreach ($file in $allPs1Files) { + Write-Verbose "Checking file: $($file.FullName)" + + $declaredFunctions = @() + $content = Get-Content -Path $file.FullName -Raw + $functionMatches = [regex]::Matches($content, '(?m)^function\s+([\w-]+)') + + foreach ($match in $functionMatches) { + $declaredFunctions += $match.Groups[1].Value.ToLowerInvariant() + } + + if ($declaredFunctions.Count -eq 0) { + Write-Host "No functions found in file: $($file.Name)" + } + + foreach ($funcName in $declaredFunctions) { + Write-Host "Expecting function: $funcName" + if (-not ($newFunctionNames -contains $funcName)) { + Write-Warning "❌ Function '$funcName' was expected but not found in loaded function list." + } + $newFunctionNames | Should -Contain $funcName + } + } + } + + It "should not attempt to load non-ps1 files like .md files or import any functions from them" { + # Arrange - Get all .md files in the target folder + $mdFiles = Get-ChildItem -Path $PSScriptRoot -Filter *.md + + # Act - Run the utility importer + Import-TocCheckerUtils -UtilsFolder $PSScriptRoot + + # Get all currently available functions with known source files + $allFunctions = Get-Command -CommandType Function | Where-Object { + $_.ScriptBlock.File -ne $null + } + + # Find functions that were (somehow) defined in .md files + $mdBasedFunctions = $allFunctions | Where-Object { + $_.ScriptBlock.File -like '*.md' + } + + # Assert - No function should originate from a .md file + $mdBasedFunctions | Should -BeNullOrEmpty + + # Additional safety check - No .md file should have been dot-sourced at all + foreach ($mdFile in $mdFiles) { + $mdFile.FullName | Should -Not -BeIn $allFunctions.ScriptBlock.File + } + } +} \ No newline at end of file diff --git a/doc/articles/check-toc-utilities/Import-TocCheckerUtils.ps1 b/doc/articles/check-toc-utilities/Import-TocCheckerUtils.ps1 new file mode 100644 index 000000000000..2a6579723f1e --- /dev/null +++ b/doc/articles/check-toc-utilities/Import-TocCheckerUtils.ps1 @@ -0,0 +1,40 @@ +function Import-TocCheckerUtils { + [CmdletBinding()] + param ( + [string]$UtilsFolder = $PSScriptRoot, + [string[]]$ExcludeFiles = @() + ) + + # Resolve script location if UtilsFolder is not set or invalid + if (-not $UtilsFolder -or -not (Test-Path $UtilsFolder)) { + $UtilsFolder = Split-Path -Path $MyInvocation.MyCommand.Path -Parent + } + + if (-not (Test-Path $UtilsFolder)) { + throw "The specified UtilsFolder path '$UtilsFolder' does not exist." + } + + Write-Host "Collecting TOC Checker Utils from: $UtilsFolder" + + # Get the path of the current script to exclude it + $mySelf = $MyInvocation.MyCommand.Path + + # Collect all .ps1 files, excluding this script, excluded files, and test scripts + $ps1Files = Get-ChildItem -Path $UtilsFolder -Filter *.ps1 | Where-Object { + $_.FullName -ne $mySelf -and + ($_.Name -notin $ExcludeFiles) -and + ($_.Name -notmatch '\.Test\.ps1$') + } + + foreach ($file in $ps1Files) { + $absolutePath = $file.FullName + try { + . $absolutePath + Write-Host "✅ Dot-sourced: $($file.Name)" + } + catch { + Write-Warning "❌ Failed to dot-source: $($file.Name)" + Write-Warning $_ + } + } +} \ No newline at end of file diff --git a/doc/articles/check-toc-utilities/Overview.md b/doc/articles/check-toc-utilities/Overview.md new file mode 100644 index 000000000000..c88c2deefb16 --- /dev/null +++ b/doc/articles/check-toc-utilities/Overview.md @@ -0,0 +1,59 @@ +--- +uid: Uno.Contributing.check-toc.Overview +--- +# Toc Checker Overview + +The [`check_toc.ps1`](../check_toc.ps1) script helps maintain the structure and integrity of your documentation by: + +- Detecting **broken links** in [toc.yml](../toc.yml) +- Identifying **Markdown files** recursive to `articles` folder that are **not referenced** in the TOC +- Providing a YAML-formatted suggestion (`toc_additions.yml.tmp`) for missing entries + +> [!NOTE] +> This script is currently not part of the CI pipeline. Contributors can run it manually to ensure link consistency. + +## 🛠️ Usage + +1. Open a **PowerShell terminal** at the **root** of your locally cloned Uno repository. +2. Navigate to the [`doc/articles`](../../articles/) directory: + + ```ps1 + cd doc/articles + ``` + + > [!IMPORTANT] + > The script must be executed from within `doc/articles` to correctly resolve relative paths in TOC entries. + +3. Run the script: + + ```ps1 + & .\check_toc.ps1 + ``` + +4. Open the generated file `toc_additions.yml.tmp` to see which files should be added to `toc.yml`. + +> [!TIP] +> Run with `-Verbose` to see detailed output and trace the script’s progress. +> Consider using an external Power-Shell Terminal in this case, since some IDE like vs code might limit the output lines you can review after executing with `-Verbose` flag. + +## 🔍 What It Does + +The script performs the following Check-up Tasks: + +- **Parses `toc.yml`** and extracts Markdown (`.md`) and `xref:` links. +- **Scans the current directory recursively** to collect all Markdown files. +- **Compares files in the directory vs. TOC entries**, excluding known or auto-generated ones (e.g., `implemented-views.md`, `roadmap.md`, etc.) +- **Identifies files** that: + - Are referenced in the TOC but don't exist (broken links) + - Exist in the project but are missing from the TOC (unlinked files) + +Utility functions are dynamically imported from [`Import-TocCheckerUtils.ps1`](./Import-TocCheckerUtils.ps1), providing modular support for file parsing, Markdown processing, and header detection. + +## 📄 Related Pages + +- [The Uno docs website and DocFX](xref:Uno.Contributing.DocFx) +- [Utility Functions for `check_toc`](xref:Uno.Contributing.check-toc.Utilities) + +## 🌐 Further Reading + +- [!INCLUDE [Clean Architecture Principles Inline](xref:Uno.Clean-Architecture-Inline)] diff --git a/doc/articles/check-toc-utilities/Utilities.md b/doc/articles/check-toc-utilities/Utilities.md new file mode 100644 index 000000000000..fed779e5061a --- /dev/null +++ b/doc/articles/check-toc-utilities/Utilities.md @@ -0,0 +1,41 @@ +--- +uid: Uno.Contributing.check-toc.Utilities +--- +# Utility Functions for the TOC Checker + +*[SoC]: Separation of Concerns – Part of Clean Architecture + +The utility functions used by the `check_toc.ps1` script follow SoC principles to improve modularity, maintainability, and testability. These helpers are dynamically imported during script execution via the [`Import-TocCheckerUtils.ps1`](./Import-TocCheckerUtils.ps1) script and encapsulate common logic such as file enumeration, header parsing, and output generation. + +> [!TIP] +> Keeping utility functions well-documented and separated from the main script logic helps contributors understand, maintain, and extend the tooling efficiently. + +For an overview of how these utilities integrate with the main script, see the [TOC Checker Script Overview](xref:Uno.Contributing.check-toc.Overview). + +## Coding Standards + +Adhere to the project’s coding standards to ensure consistency, readability across contributions. + +## CmdletBinding Usage + +Use [`[CmdletBinding()]`](https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute?view=powershell-7.5) in all advanced functions. This: + +- Enables the use of the `-Verbose` flag for detailed logging +- Integrates better with script pipelines and error handling +- Improves clarity when debugging or reviewing logs + +By following these practices, utility scripts remain robust, predictable, and easier to support. + + + + +## Related Pages + +- [TOC Checker Script Overview](xref:Uno.Contributing.check-toc.Overview) +- [The Uno docs website and DocFX](xref:Uno.Contributing.DocFx) + +## 🌐 Further Reading + +- [!INCLUDE [Clean Architecture Principles Inline](../includes/clean-architecture-principles-inline.md)] + +[SoC]: https://en.wikipedia.org/wiki/Separation_of_concerns diff --git a/doc/articles/check_toc.ps1 b/doc/articles/check_toc.ps1 index 675221ae8ace..b42771dbff5a 100644 --- a/doc/articles/check_toc.ps1 +++ b/doc/articles/check_toc.ps1 @@ -1,36 +1,91 @@ -# -# Reports dead links in the table of contents used by docfx and .md files that aren't linked anywhere in the TOC -# - -$expectedMissingLinks = '.\implemented-views.md' #Implemented views is generated by the CI build -$expectedUnlinked = '.\roadmap.md' -$tempFileName = 'toc_additions.yml.tmp' - -$allMdFiles = Get-ChildItem -Recurse -Filter *.md | Resolve-Path -Relative | Where-Object {$_.IndexOf('\implemented\') -lt 0} -$toc = Get-Content -Path .\toc.yml -$allMdLinks = $toc | foreach {$_ -split ":"} | foreach {$_.Trim(' ')} | foreach {'.\' + $_} | foreach {$_ -replace '/', '\'} | Where-Object {$_.EndsWith(".md")} -$badLinks = $allMdLinks | Where-Object {-not (Test-Path -Path $_)} | Where-Object {-not ($expectedMissingLinks -contains $_)} -$unlinkedFiles = $allMdFiles | Where-Object {-not ($allMdLinks -contains $_)} | Where-Object {-not ($expectedUnlinked -contains $_)} -if ($badLinks.Length -gt 0) { - Write-Host "Bad links found in toc.yml: $badLinks" -ForegroundColor Red -} -else { - Write-Host 'No bad links found in toc.yml' -} -if ($unlinkedFiles.Length -gt 0) { - Write-Host ".md files not linked in toc.yml: $unlinkedFiles" - '# UNLINKED .MD FILES: Add to toc.yml in appropriate category' | Out-File $tempFileName - $unlinkedFiles | foreach { - $header = Get-Content $_ | Where-Object {$_.StartsWith('#')}[0] | foreach {$_.Trim('#').Trim(' ')} | Select -First 1 - " - name: $header" | Out-File $tempFileName -Append - $link = $_.Trim('.').Trim('\') - " href: $link" | Out-File $tempFileName -Append - } - Write-Host "Missing links added to $tempFileName" -ForegroundColor Green -} -else { - Write-Host 'No unlinked files found' - if (Test-Path $tempFileName) { - '# No unlinked .md files' | Out-File $tempFileName - } +function Invoke-TocCheck { + [Alias('Check-Toc', 'Toc_Checker')] + [CmdletBinding(SupportsShouldProcess = $true), ConfirmImpact = "Medium"] + param ( + [string]$TocFilePath = ".\toc.yml", + [string[]]$ExpectedMissingLinks = @('.\implemented-views.md'), + [string[]]$ExpectedUnlinked = @('.\roadmap.md'), + [string]$TempFileName = "toc_additions.yml.tmp" + ) + + begin { + Write-Verbose "Loading utility scripts from Import-TocCheckerUtils.ps1" + . .\check-toc-utilities\Import-TocCheckerUtils.ps1 + Import-TocCheckerUtils -UtilsFolder $PSCommandPath.Replace('check-toc.ps1', 'check-toc-utilities') -ExcludeFiles @(Get-IrrelevantFiles) + Write-Host "Dot-sourced Functions in Scope:" -ForegroundColor Cyan + Get-Command -CommandType Function | + Where-Object { $_.Name -match 'Get-MarkdownHeader|Get-UnlinkedFiles' } | + Select-Object -ExpandProperty Name | + ForEach-Object { Write-Verbose $_ } + + Write-Information "Reports dead links in the table of contents used by DocFx and .md files that aren't linked anywhere in the TOC" + Write-Information "See the output file $TempFileName for a list of .md files that are not linked in the TOC" + Write-Information "Use -Verbose to see more details" + } + + process { + Write-Host "The current directory is: $PWD" + Write-Verbose 'Collecting all Markdown filenames recursively below the execution directory' + $allMdFiles = Get-ChildItem -Recurse -Filter *.md | Resolve-Path -Relative | Where-Object { + $_.IndexOf('\implemented\') -lt 0 -and + $_.IndexOf('\included\') -lt 0 + } + Write-Verbose "Done! Found $($allMdFiles.Count) .md files" + + Write-Verbose "Reading the content of the TOC file: $TocFilePath" + $toc = Get-Content -Path $TocFilePath + Write-Verbose "Done!" + + Write-Verbose 'Extracting all .md links from the TOC file' + $allMdLinks = $toc | + Where-Object { $_ -match 'href:\s*(?!xref:|https?://)(\S+\.md)(#[\w\-]+)?' } | + ForEach-Object { '.\' + ($matches[1] -replace '/', '\') } | + Sort-Object -Unique + Write-Verbose 'Done!' + + Write-Verbose 'Extracting all xref links from the TOC file' + $allXrefLinksInToc = $toc | + Where-Object { $_ -match 'href: xref:(\S+)' } | + ForEach-Object { $matches[1] } | + Sort-Object -Unique + Write-Verbose 'Done!' + + Write-Verbose "Checking for any link in TOC that points to a non-existing file" + $badLinks = $allMdLinks | + Where-Object { + -not (Test-Path -Path $_) -and + -not ($ExpectedMissingLinks -contains $_) + } + if ($badLinks.Count -gt 0) { + Write-Host "Bad links found in toc.yml: $badLinks" -ForegroundColor Red + } else { + Write-Host 'No bad links found in toc.yml' + } + + Write-Verbose 'Checking for unlinked files' + $unlinkedFiles = Get-UnlinkedFiles -allMdFiles $allMdFiles -allMdLinks $allMdLinks -allXrefLinksInToc $allXrefLinksInToc -expectedUnlinked $ExpectedUnlinked -Verbose + + if ($unlinkedFiles.Count -gt 0) { + Write-Host ".md files not linked in toc.yml: $unlinkedFiles" + '# UNLINKED .MD FILES: Add to toc.yml in appropriate category' | Out-File $TempFileName + $unlinkedFiles | ForEach-Object { + $lines = Get-Content $_ -TotalCount 10 + $header = Get-MarkdownHeader -Lines $lines + + " - name: $header" | Out-File $TempFileName -Append + $link = $_.TrimStart('.', '\') + " href: $link" | Out-File $TempFileName -Append + } + Write-Host "Missing links added to $TempFileName" -ForegroundColor Green + } else { + Write-Host 'No unlinked files found' + if (Test-Path $TempFileName) { + '# No unlinked .md files' | Out-File $TempFileName + } + } + } + + end { + Write-Verbose "TOC check completed." + } } diff --git a/doc/articles/contributing/Documentation/anchor-links.md b/doc/articles/contributing/Documentation/anchor-links.md new file mode 100644 index 000000000000..ebed11a5cabd --- /dev/null +++ b/doc/articles/contributing/Documentation/anchor-links.md @@ -0,0 +1,52 @@ +--- +uid: Uno.Contributing.Documentation.Anchor-links +--- + +# Anchor Links in Documentation + +Anchor links (also called **fragment links**) allow you to link directly to a specific section within a doc file. They are useful for cross-referencing headings and improving navigation in long documentation pages. + +## How Anchor Links Work + +Anchor links in DocFX (and Markdig) are automatically generated from Markdown headings. For example: + +```markdown +## My Section Title +``` + +Generates the anchor: + +```md +#my-section-title +``` + +You can then link to this section using: + +```markdown +[Jump to My Section](#my-section-title) +``` + +> [!NOTE] +> Anchors are generated by converting the heading to lowercase and replacing spaces and most special characters with hyphens. + +## Best Practices + +- ✅ Use anchor links to help readers jump between related sections. +- ✅ Always verify that the anchor exists to avoid broken links. +- 🔶 Avoid using identical headings in the same file – they will result in duplicate anchors. + +## Linking to Anchors in Other Files + +You can link to a specific heading in another Markdown file like this: + +```markdown +[Go to Subsection](otherfile.md#subsection-heading) +``` + +Make sure the linked file is part of the TOC or referenced properly so that DocFX includes it in the output. + +## Common Pitfalls + +- ❌ `#My-Section-Title` → won't work (wrong casing) +- ❌ `#my section title` → won't work (missing `-` between the words) +- ❌ Linking to headings that are dynamically generated (e.g., via include files) may break if anchors are not preserved diff --git a/doc/articles/uno-development/doc-on-docs.md b/doc/articles/contributing/Documentation/doc-on-docs.md similarity index 85% rename from doc/articles/uno-development/doc-on-docs.md rename to doc/articles/contributing/Documentation/doc-on-docs.md index e26d40983041..1d15ee022554 100644 --- a/doc/articles/uno-development/doc-on-docs.md +++ b/doc/articles/contributing/Documentation/doc-on-docs.md @@ -2,25 +2,25 @@ uid: Uno.Contributing.Docs --- -# Contributing docs to Uno Platform +# Contributing Documentation to Uno Platform Good documentation is essential, and writing docs is a valued contribution that makes Uno more useful for everybody. This article covers *when* to write docs and *what* you should write, with a focus on two of the most common forms of documentation: step-by-step guides (ie howtos or tutorials), and feature documentation. We have a few different fill-in-the-blanks style templates, linked below. -For the DocFX tool used to build the docs website, see [more info here](docfx.md). +For the DocFX tool used to build the docs website, see [more info here](xref:Uno.Contributing.DocFx). ## Key links -* how-to template: https://github.com/unoplatform/uno/blob/master/doc/.howto-template.md -* WinUI feature template: https://github.com/unoplatform/uno/blob/master/doc/.feature-template.md -* Uno-only feature template: https://github.com/unoplatform/uno/blob/master/doc/.feature-template-uno-only.md +* [How-to template](xref:Uno.Doc-Templates.How-To) +* [WinUI feature template](xref:Uno.Doc-Templates.Feature.Uno-Specifics) +* [Uno-only feature template](xref:Uno.Doc-Templates.Feature.Uno-only) ## Resources Some useful resources on writing good technical documentation: -* [ReactiveUI docs style guide](https://www.reactiveui.net/contribute/content-style-guide/) +* [ReactiveUI docs style guide](https://www.reactiveui.net/contribute/content-style-guide/grammar-and-mechanics.html) * [Divio's Documentation System](https://documentation.divio.com/) ## Writing step-by-step guides @@ -29,7 +29,7 @@ Step-by-step guides that address a particular problem or use case that multiple * For longer tutorials, it's fine to split the content over multiple pages. * Guides should always be accompanied by working code. Standalone applications should be added to the [Uno.Samples repository](https://github.com/unoplatform/Uno.Samples) and linked to from the associated tutorial. -* Use the [how-to template](https://github.com/unoplatform/uno/blob/master/doc/.howto-template.md) as a starting point. +* Use the [how-to template](xref:Uno.Doc-Templates.How-To) as a starting point. * Structure guides as a series of clear, actionable steps. After carrying out every step as described, the user should end up with working code that demonstrates the objective of the guide (either a standalone sample, or a new feature in their existing app). ## Documenting features @@ -44,7 +44,7 @@ There's two different cases: Uno's API matches WinUI's API, and most of the time, a new Uno feature will map to an existing WinUI feature. -In this case, to the extent that the behavior you're adding is the same as the WinUI behavior, you **don't** need to add documentation. The existing WinUI documentation is fine. It's already linked to from [Uno's reference documentation](../implemented-views.md). +In this case, to the extent that the behavior you're adding is the same as the WinUI behavior, you **don't** need to add documentation. The existing WinUI documentation is fine. It's already linked to from [Uno's reference documentation](../../implemented-views.md). What if the Uno behavior deviates from WinUI behavior? @@ -58,7 +58,7 @@ In those cases, it's important to add documentation. Copy the [WinUI feature tem Rarely, features are added to Uno Platform that aren't part of WinUI (`VisibleBoundsPadding` and `ElevatedView` are two examples). Somewhat more commonly, platform-specific functionality or options are added to an existing feature. -It's important to document these novel features when you add them, since they aren't covered anywhere else. Again, copy the [Uno-only feature template here](https://github.com/unoplatform/uno/blob/master/doc/.feature-template-uno-only.md) to the [features directory](https://github.com/unoplatform/uno/tree/master/doc/articles/features) and fill in the sections. +It's important to document these novel features when you add them, since they aren't covered anywhere else. Again, copy the [Uno-only feature template here](xref:Uno.Doc-Templates.Feature.Uno-Only) to the [features directory](../../features/) and fill in the sections. ## Updating the documentation from linked repositories diff --git a/doc/articles/contributing/Documentation/docfx.md b/doc/articles/contributing/Documentation/docfx.md new file mode 100644 index 000000000000..98ec860a2397 --- /dev/null +++ b/doc/articles/contributing/Documentation/docfx.md @@ -0,0 +1,145 @@ +--- +uid: Uno.Contributing.DocFx +--- + + + +# The Uno documentation website and DocFX + +Uno Platform's docs website uses [DocFX](https://dotnet.github.io/docfx/) to convert Markdown (.md) files in the [articles folder](../../../articles) into [HTML files](xref:Uno.Documentation.Intro). + +## Linking to the Table of Contents + +Normally when you add a new markdown file, you also add it to [articles/toc.yml](../../toc.yml). This allows it to show up in the left sidebar TOC on the docs website. + +### Checking Links in the Table of Contents + +To ensure that your file is correctly linked and nothing is missing, you can use the [Toc Checker](xref:Uno.Contributing.check-toc.Overview). This helps identify unreferenced files and invalid links automatically. + +## DocFX-flavored Markdown + +DocFX supports extended Markdown syntaxes that are treated specially when converting to html. + +### Formatted blockquotes + +You can use [specially-styled blockquotes](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#note-warningtipimportant), to call special attention to particular information. + +The following note types are supported, including an example for each one: + +```markdown +> [!NOTE] +> Useful information that users should know, even when skimming content. +``` + +> [!NOTE] +> Useful information that users should know, even when skimming content. + +```markdown +> [!TIP] +> Helpful advice for doing things better or more easily. +``` + +> [!TIP] +> Helpful advice for doing things better or more easily. + +```markdown +> [!IMPORTANT] +> Key information users need to know to achieve their goal. +``` + +> [!IMPORTANT] +> Key information users need to know to achieve their goal. + +```markdown +> [!CAUTION] +> Advises about risks or negative outcomes of certain actions. +``` + +> [!CAUTION] +> Advises about risks or negative outcomes of certain actions. + +```markdown +> [!WARNING] +> Urgent info that needs immediate user attention to avoid problems. +``` + +> [!WARNING] +> Urgent info that needs immediate user attention to avoid problems. + +### Tabs + +DocFX can generate tabs. Make sure to follow the [syntax specification](https://dotnet.github.io/docfx/docs/markdown.html#tabs) precisely. + +#### Example + +Markdown: + +```md +# [WinUI](#tab/tabid-1) + +`Microsoft.UI.Xaml.FrameworkElement` + +# [UWP](#tab/tabid-2) + +`Windows.UI.Xaml.FrameworkElement` + +--- +``` + +Html output: + +# [WinUI](#tab/tabid-1) + +`Microsoft.UI.Xaml.FrameworkElement` + +# [UWP](#tab/tabid-2) + +`Windows.UI.Xaml.FrameworkElement` + +--- + +> [!NOTE] +> Use `---` in the Markdown sample is Important, to not include more Content in the tabbed area than actually wanted, but will not be rendered in the served documentation. +> It is possible to use `***` alternatively for the same task. + + + +## Building docs website locally with DocFX + +Sometimes, you may want to run DocFX locally to ensure that your changes render correctly in HTML. To do this, first generate the *implemented views* documentation. If you've added any new documentation files, make sure to [validate the contents of the TOC](#checking-links-in-the-table-of-contents) to minimize warnings and avoid potential build errors. + +### Run DocFX locally + +To run DocFX locally and check the resulting html: + +1. Open the `Uno.UI-Tools.slnf` solution filter in the `src` folder with Visual Studio. +2. Edit the properties of the `Uno.UwpSyncGenerator` project. Under the 'Debug' tab, set Application arguments to "doc". +3. Set `Uno.UwpSyncGenerator` as startup project and run it. It may fail to generate the full implemented views content; if so, it should still nonetheless generate stubs so that DocFX can run successfully. +4. Open a Terminal at the Root Directory of your locally cloned Uno Repository. +5. Install docfx globally: `dotnet tool install -g docfx` +6. Run the following command: `docfx build doc/docfx.json` and attach any nested folder name you want by adding `-o your-nested-output-path`, default: `_site` +7. When DocFX builds successfully, it will create the html output at `uno-clone-repo\doc\[your-nested-output-path\]_site`, which you can serve by one of the following options: + a. Execute the command `docfx serve doc/docfx.json` in your terminal. + b. Use a [local server](#use-a-local-server). + +### Use a local server + +You can use `dotnet-serve` as a simple command-line HTTP server for example. + +1. Install `dotnet-serve` using the following command: `dotnet tool install --global dotnet-serve`. For more info about its usage and options,[please refer to the documentation](https://github.com/natemcmaster/dotnet-serve). +2. Using the command prompt, navigate to `C:\src\Uno.UI\docs-local-dist\_site` (replacing `C:\src\Uno.UI` with your local path to the Uno.UI repository) and run the following command `dotnet serve -o -S`. This will start a simple server with HTTPS and open the browser directly. + +## Run the documentation generation performance test + +If needed, you can also run a script that will give you a performance summary for the documentation generation. + +To run the script on Windows: + +1. Make sure `crosstargeting_override.props` is not defining UnoTargetFrameworkOverride +2. Open a Developer Command Prompt for Visual Studio (2019 or 2022) +3. Go to the uno\build folder (not the uno\src\build folder) +4. Run the `run-doc-generation.cmd` script; make sure to follow the instructions + +## Import Uno Extensions and Tools docs + +[!INCLUDE [Import external docs](../../external/uno.extensions/doc/README.md)] diff --git a/doc/articles/uno-development/Internal-DependencyProperty-Generator.md b/doc/articles/contributing/Internal-DependencyProperty-Generator.md similarity index 100% rename from doc/articles/uno-development/Internal-DependencyProperty-Generator.md rename to doc/articles/contributing/Internal-DependencyProperty-Generator.md diff --git a/doc/articles/uno-development/Internal-WeakEventHelper.md b/doc/articles/contributing/Internal-WeakEventHelper.md similarity index 100% rename from doc/articles/uno-development/Internal-WeakEventHelper.md rename to doc/articles/contributing/Internal-WeakEventHelper.md diff --git a/doc/articles/uno-development/Uno-UI-Layouting-Android.md b/doc/articles/contributing/Uno-UI-Layouting-Android.md similarity index 99% rename from doc/articles/uno-development/Uno-UI-Layouting-Android.md rename to doc/articles/contributing/Uno-UI-Layouting-Android.md index c49d2901c751..ddc890b19f3a 100644 --- a/doc/articles/uno-development/Uno-UI-Layouting-Android.md +++ b/doc/articles/contributing/Uno-UI-Layouting-Android.md @@ -1,5 +1,5 @@ --- -uid: Uno.Contributing.LayoutingAndroid +uid: Uno.Contributing.Layouting.Android --- # Layouting in Android diff --git a/doc/articles/uno-development/Uno-UI-Layouting-iOS.md b/doc/articles/contributing/Uno-UI-Layouting-iOS.md similarity index 99% rename from doc/articles/uno-development/Uno-UI-Layouting-iOS.md rename to doc/articles/contributing/Uno-UI-Layouting-iOS.md index 1c2d94c2b1b9..637d83c51961 100644 --- a/doc/articles/uno-development/Uno-UI-Layouting-iOS.md +++ b/doc/articles/contributing/Uno-UI-Layouting-iOS.md @@ -1,5 +1,5 @@ --- -uid: Uno.Contributing.LayoutingiOS +uid: Uno.Contributing.Layouting.iOS --- # Layouting in iOS diff --git a/doc/articles/uno-development/api-extensions.md b/doc/articles/contributing/api-extensions.md similarity index 100% rename from doc/articles/uno-development/api-extensions.md rename to doc/articles/contributing/api-extensions.md diff --git a/doc/articles/uno-development/assets/SamplesApp.png b/doc/articles/contributing/assets/SamplesApp.png similarity index 100% rename from doc/articles/uno-development/assets/SamplesApp.png rename to doc/articles/contributing/assets/SamplesApp.png diff --git a/doc/articles/uno-development/contributing-intro.md b/doc/articles/contributing/contributing-intro.md similarity index 59% rename from doc/articles/uno-development/contributing-intro.md rename to doc/articles/contributing/contributing-intro.md index fb8c3d540d68..03f8a09cf365 100644 --- a/doc/articles/uno-development/contributing-intro.md +++ b/doc/articles/contributing/contributing-intro.md @@ -1,26 +1,24 @@ --- uid: Uno.Contributing.Intro --- - + # Contributing to Uno Everyone is welcome to contribute to the Uno Platform. Here you'll find useful information for new and returning contributors. For starters, please read our [Code of Conduct](https://github.com/unoplatform/uno/blob/master/CODE_OF_CONDUCT.md), which sets out our commitment to an open, welcoming, harassment-free community. -If you're wondering where to start, [read about ways to contribute to Uno](ways-to-contribute.md). Or, you can peruse the list of [first-timer-friendly open issues](https://github.com/unoplatform/Uno/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). +If you're wondering where to start, [read about ways to contribute to Uno](xref:Uno.Contributing.WaysToContribute). Or, you can peruse the list of [first-timer-friendly open issues](https://github.com/unoplatform/Uno/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). ## Understanding the Uno codebase -For a refresher on what Uno is and what it does and does not do, read [What is the Uno Platform?](../intro.md) +For a refresher on what Uno is and what it does and does not do, read [What is the Uno Platform?](xref:Uno.Documentation.Intro) -Get an [in-depth introduction to how Uno works](uno-internals-overview.md), or jump straight to platform-specific details on how Uno works on [Android](uno-internals-android.md), [iOS](uno-internals-ios.md), [WebAssembly](uno-internals-wasm.md), or [macOS](uno-internals-macos.md). +Get an [in-depth introduction to how Uno works](xref:Uno.Contributing.Overview), or jump straight to platform-specific details on how Uno works on [Android](xref:Uno.Contributing.Android), [iOS](xref:Uno.Contributing.iOS), [WebAssembly](xref:Uno.Contributing.Wasm), or [macOS](xref:Uno.Contributing.macOS). ## Building and debugging Uno -For the prerequisites you'll need, as well as useful tips like using [solution filters](https://learn.microsoft.com/visualstudio/ide/filtered-solutions) and cross-targeting overrides to quickly load and build Uno for a single platform, start with the guide to [Building Uno.UI](building-uno-ui.md). The guide to [Debugging Uno.UI](debugging-uno-ui.md) will show you how to debug Uno.UI code either in the included UI samples or in an application outside the Uno.UI solution. - -If you're doing development for Uno's macOS support, you'll need to build and run Uno using Visual Studio for Mac. [There's a separate guide for that here](xref:Uno.Contributing.BuildingUnomacOS). +For the prerequisites you'll need, as well as useful tips like using [solution filters](https://learn.microsoft.com/visualstudio/ide/filtered-solutions) and cross-targeting overrides to quickly load and build Uno for a single platform, start with the guide to [Building Uno.UI](xref:Uno.Contributing.BuildingUno). The guide to [Debugging Uno.UI](xref:Uno.Contributing.DebuggingUno) will show you how to debug Uno.UI code either in the included UI samples or in an application outside the Uno.UI solution. You can contribute to Uno directly from your browser using GitPod, [find out how](xref:Uno.Features.Gitpod). @@ -28,7 +26,7 @@ Whether you're fixing a bug or working on a new feature, [inspecting the visual ## Writing code in Uno -See [Uno's code conventions and common patterns here](../contributing/guidelines/code-style.md). +See [Uno's code conventions and common patterns here](xref:Uno.Contributing.CodeStyle). ## Implementing a new feature @@ -46,9 +44,9 @@ This app is available live at these locations, built from the default branch: Uno's stability rests upon a comprehensive testing suite. A code contribution usually isn't complete without a test. -See the [Guidelines for creating tests](../contributing/guidelines/creating-tests.md) for an overview of the different types of tests used by Uno, and how to add one. +See the [Guidelines for creating tests](xref:Uno.Contributing.Tests.CreatingTests) for an overview of the different types of tests used by Uno, and how to add one. -[Working with the Samples Applications](working-with-the-samples-apps.md) provides instructions on adding a new UI sample to Uno, and authoring a UI Test to verify that the sample works. +[Working with the Samples Applications](xref:Uno.Contributing.SamplesApp) provides instructions on adding a new UI sample to Uno, and authoring a UI Test to verify that the sample works. ## Creating a Pull Request @@ -58,23 +56,23 @@ Uno uses [Git](https://git-scm.com/) for version control, and GitHub to host the [Tutorials | Atlassian](https://www.atlassian.com/git/tutorials) > [!IMPORTANT] -> Before you commit your code, take a minute to familiarize yourself with the [Conventional Commits format](git-conventional-commits.md) Uno uses. +> Before you commit your code, take a minute to familiarize yourself with the [Conventional Commits format](xref:Uno.Contributing.ConventionalCommits) Uno uses. -Read the [Guidelines for pull requests](../contributing/guidelines/pull-requests.md) in Uno. +Read the [Guidelines for pull requests](xref:Uno.Contributing.PullRequests) in Uno. -Uno's CI process [runs a tool to guard against inadvertent binary breaking changes](../contributing/guidelines/breaking-changes.md). +Uno's CI process [runs a tool to guard against inadvertent binary breaking changes](xref:Uno.Contributing.BreakingChanges). ## Info for the core team This section covers practices and utilities used by core maintainers. -Uno uses [Dependabot to automatically update external dependencies](../contributing/guidelines/updating-dependencies.md). +Uno uses [Dependabot to automatically update external dependencies](xref:Uno.Contributing.UpdatingDependencies). -Read the [guidelines for issue triage](../contributing/guidelines/issue-triage.md). +Read the [guidelines for issue triage](xref:Uno.Contributing.UpdatingDependencies). -Tools and procedures for creating stable releases are described [here](release-procedure.md). +Tools and procedures for creating stable releases are described [here](xref:Uno.Contributing.ReleaseProcedure). -Build artifacts produced by the CI are documented [here](../contributing/build-artifacts.md). +Build artifacts produced by the CI are documented [here](xref:Uno.Contributing.Artifacts). ### More questions? diff --git a/doc/articles/uno-development/git-conventional-commits.md b/doc/articles/contributing/git/git-conventional-commits.md similarity index 100% rename from doc/articles/uno-development/git-conventional-commits.md rename to doc/articles/contributing/git/git-conventional-commits.md diff --git a/doc/articles/contributing/guidelines/pull-requests.md b/doc/articles/contributing/git/pull-requests.md similarity index 89% rename from doc/articles/contributing/guidelines/pull-requests.md rename to doc/articles/contributing/git/pull-requests.md index 7a77f104d638..c31fbb0504b6 100644 --- a/doc/articles/contributing/guidelines/pull-requests.md +++ b/doc/articles/contributing/git/pull-requests.md @@ -10,7 +10,7 @@ If you don't know what a pull request is, read the [About pull requests document If you are an outside contributor, please fork the Uno Platform repository you would like to contribute to your account. See the GitHub documentation for [forking a repo](https://help.github.com/articles/fork-a-repo/) if you have any questions about this. -Make sure the repository can build and all tests pass, as well as follow the current [coding guidelines](code-style.md). +Make sure the repository can build and all tests pass, as well as follow the current [coding guidelines](xref:Uno.Contributing.CodeStyle). Pull requests should all be made to the **master** branch. @@ -44,7 +44,7 @@ Make sure to rebase your work on the latest default branch of the Uno repository **Commit/Pull Request Format** -All commits **must** be in the [Conventional Commits format](../../uno-development/git-conventional-commits.md), otherwise the build will fail. +All commits **must** be in the [Conventional Commits format](xref:Uno.Contributing.ConventionalCommits), otherwise the build will fail. We use this convention to automatically generate release notes for new releases, and means that your commit messages will appear untouched in the release notes. @@ -64,7 +64,7 @@ Make sure that: When opening a PR, you'll see the description is filled by a template. Make sure to read through the template and fill the missing parts in it. -If you haven't [added tests](creating-tests.md) appropriate to your changes, the reviewers will probably ask you to add some. +If you haven't [added tests](xref:Uno.Contributing.Tests.CreatingTests) appropriate to your changes, the reviewers will probably ask you to add some. ## Reviewing diff --git a/doc/articles/contributing/git/sourcecontrol-overview.md b/doc/articles/contributing/git/sourcecontrol-overview.md new file mode 100644 index 000000000000..aa8159927d44 --- /dev/null +++ b/doc/articles/contributing/git/sourcecontrol-overview.md @@ -0,0 +1,20 @@ +--- +uid: Uno.Contributing.Source-Control +--- +# Source Control Overview + +## Common Source Control Applications + +Here you can find some common Source Control Applications that can also be used for Uno Applications and Contributing to Uno Platform: + +- Git Bash +- Git GUI +- GitHub (Web, Desktop, Mobile) +- Atlassian SourceTree (Desktop) + +## 📄 Related Pages + +- [Conventional Commits](xref:Uno.Contributing.ConventionalCommits) +- [Pull Requests](xref:Uno.Contributing.PullRequests) +- [Git Pod](xref:Uno.Features.Gitpod) +- [Codespaces](xref:Uno.Features.Codespaces) diff --git a/doc/articles/contributing/guidelines/breaking-changes.md b/doc/articles/contributing/guidelines/breaking-changes.md index 7a23ed34bc97..da8a1a43e03c 100644 --- a/doc/articles/contributing/guidelines/breaking-changes.md +++ b/doc/articles/contributing/guidelines/breaking-changes.md @@ -11,7 +11,7 @@ go unnoticed. As [part of our continuous integration process](https://github.com This process only diffs against previous versions of Uno, not against the WinUI assemblies, so it doesn't pick up all forms of mismatches. There are [some inconsistencies](https://github.com/unoplatform/uno/pull/1300) dating from before SyncGenerator was added. At some point it might be a good idea to extend SyncGenerator tool to try to report them all (or even automatically fix them) -Breaking changes must be marked as such when committed using the [Conventional Commits formatting](../../uno-development/git-conventional-commits.md). +Breaking changes must be marked as such when committed using the [Conventional Commits formatting](xref:Uno.Contributing.ConventionalCommits). ## When are binary breaking changes acceptable? @@ -21,7 +21,7 @@ Changes that break compatibility with the public API surface of WinUI are genera ### Restoring cross-platform compatibility - ok, but discuss with core team -In some cases, Uno's existing API is close to WinUI, but not identical. (Hypothetical example: a property with type `DependencyObject[]` on Uno, but type `IList` on WinUI.) This is mostly the case for older code that was written before the use of [generated `NotImplemented` stubs](../../uno-development/uno-internals-overview.md#generated-notimplemented-stubs) and the `PackageDiff` tool, which act in combination to prevent these kinds of errors when implementing new features. +In some cases, Uno's existing API is close to WinUI, but not identical. (Hypothetical example: a property with type `DependencyObject[]` on Uno, but type `IList` on WinUI.) This is mostly the case for older code that was written before the use of [generated `NotImplemented` stubs](xref:Uno.Contributing.Overview#generated-notimplemented-stubs) and the `PackageDiff` tool, which act in combination to prevent these kinds of errors when implementing new features. In these cases, we do want to align Uno with WinUI, even at the expense of a breaking change. However, we tend to be more careful with when we merge these changes, compared to other bugfixes. We prefer to 'batch' many such breaking changes into a single stable release cycle, rather than wear out consumers' patience with a steady trickle of breaking changes each release. @@ -33,13 +33,13 @@ Note that some cases may be sufficiently benign that the breaking change is acce The diff tool guards against all changes to Uno's public API surface, including functionality that has no equivalent in WinUI's API surface. -In the cases where these Uno-only APIs are exposed intentionally (example: the [`VisibleBoundsPadding` behavior](../../features/VisibleBoundsPadding.md)), we would usually reject breaking changes, unless there were a very compelling reason for them. +In the cases where these Uno-only APIs are exposed intentionally (example: the [`VisibleBoundsPadding` behavior](xref:Uno.Features.VisibleBoundsPadding)), we would usually reject breaking changes, unless there were a very compelling reason for them. In other cases, this might be functionality that's inadvertently exposed - in other words, functionality that was made public when it should really have been internal. Here the validity of the breaking change should be considered on a case-by-case basis, taking into account the risk of breaking existing Uno app code (and conversely, the possibility for the Uno-only APIs to collide with 'brownfield' WinUI code). Again, the principle of 'batching' breaking changes applies. ## Adding breaking changes to the allow list -Where a breaking change is acceptable according to the above criteria, and after discussion with the core team where appropriate, it can be marked as such using the [build/PackageDiffIgnore.xml](https://github.com/unoplatform/uno/blob/master/build/PackageDiffIgnore.xml) file. +Where a breaking change is acceptable according to the above criteria, and after discussion with the core team where appropriate, it can be marked as such using the [build/PackageDiffIgnore.xml](../../../../build/PackageDiffIgnore.xml) file. Please refer to the documentation of the [Uno.PackageDiff tool](https://github.com/unoplatform/uno.PackageDiff) for more information. diff --git a/doc/articles/uno-development/building-uno-ui.md b/doc/articles/contributing/guidelines/building-uno-ui.md similarity index 86% rename from doc/articles/uno-development/building-uno-ui.md rename to doc/articles/contributing/guidelines/building-uno-ui.md index 212e0688a932..7d0bb83063e8 100644 --- a/doc/articles/uno-development/building-uno-ui.md +++ b/doc/articles/contributing/guidelines/building-uno-ui.md @@ -10,11 +10,11 @@ This article explains how to build Uno.UI locally, for instance, if you wish to - Visual Studio 2022 (17.8.1 or later) - Select the **ASP.NET and Web Development** workload - - Select the **.NET Multi-Platform App UI development`** workload + - Select the **.NET Multi-Platform App UI development** workload - Select the **.NET desktop development** workload - - To build the UWP flavor of Uno, you'll need **UWP Development**, install all recent UWP SDKs, starting from 10.0.19041 (or above or equal to `TargetPlatformVersion` line [in this file](https://github.com/unoplatform/uno/blob/master/src/Uno.CrossTargetting.targets)) -- Install (**Tools** / **Android** / **Android SDK manager**) all Android SDKs starting from 7.1 (or the Android versions `TargetFrameworks` [list used here](https://github.com/unoplatform/uno/blob/master/src/Uno.UI.BindingHelper.Android/Uno.UI.BindingHelper.Android.netcoremobile.csproj)) -- Run [Uno.Check](https://github.com/unoplatform/uno.check) on your dev machine to setup .NET Android/iOS workloads + - To build the UWP flavor of Uno, you'll need **UWP Development**, install all recent UWP SDKs, starting from 10.0.19041 (or above or equal to `TargetPlatformVersion` line [in this file](../../../../src/Uno.CrossTargetting.targets)) +- Install (**Tools** / **Android** / **Android SDK manager**) all Android SDKs starting from 7.1 (or the Android versions `TargetFrameworks` [list used here](../../../../src/Uno.UI.BindingHelper.Android/Uno.UI.BindingHelper.Android.netcoremobile.csproj)) +- Run [Uno.Check](xref:UnoCheck.UsingUnoCheck) on your dev machine to setup .NET Android/iOS workloads - Install the latest [.NET SDK](https://aka.ms/dotnet/download) from Microsoft. ## Recommended Windows hardware @@ -50,7 +50,7 @@ The step-by-step process is: 1. By default, the Uno.UI solution on the master branch is building using the WinUI API set. If you want to build against the UWP API set, you can checkout the `generated/master/uwp-autoconvert` branch. See [this section](xref:Uno.Contributing.UWPConversion) for details on this branch. 1. Make sure you don't have the Uno.UI solution opened in any Visual Studio instances. (Visual Studio may crash or behave inconsistently if it's open when the target override is changed) -1. Make a copy of the [`src/crosstargeting_override.props.sample`](https://github.com/unoplatform/uno/blob/master/src/crosstargeting_override.props.sample) file and name this copy `src/crosstargeting_override.props`. +1. Make a copy of the [`src/crosstargeting_override.props.sample`](../../../../src/crosstargeting_override.props.sample) file and name this copy `src/crosstargeting_override.props`. 1. In `crosstargeting_override.props`, uncomment the line `xxx` 1. Set the build target inside ```` to the identifier for the target platform you wish to build for (Identifiers for each platform are listed in the `crosstargeting_override.props` file), then save the file. 1. In the `src` folder, look for the solution filter (`.slnf` file) corresponding to the target platform override you've set, which will be named `Uno.UI-[Platform]-only.slnf` (or the name listed in `crosstargeting_override.props` for the selected `UnoTargetFrameworkOverride`), and open it. @@ -59,7 +59,7 @@ The step-by-step process is: - For WebAssembly and Skia you can right-click on the `Uno.UI.Runtime.WebAssembly` or `Uno.UI.Runtime.Skia.[Gtk|Wpf|X11|macOS]` project in the Solution Explorer and 'Build'. 1. Optionally adjust additional parameters in `crosstargeting_override.props`, such as `UnoDisableNetAnalyzers` which can improve the build time during debugging sessions. -Once you've built successfully, for the next steps, [consult the guide here](debugging-uno-ui.md) for debugging Uno.UI. +Once you've built successfully, for the next steps, [consult the guide here](xref:Uno.Contributing.DebuggingUno) for debugging Uno.UI. > [!IMPORTANT] > You will need to repeat the above steps 2. and subsequent when changing the active `UnoTargetFrameworkOverride` value. @@ -83,16 +83,12 @@ Note that long paths may be required when building Uno, and invalid paths errors It's recommended to build using the single-target approach, but it's also possible to build for all targets at once, if you wish. 1. If you've previously followed the single-target steps, comment out the `` line in your `crosstargeting_override.props` file. -2. Open the [Uno.UI.sln](https://github.com/unoplatform/uno/blob/master/src/Uno.UI.sln) +2. Open the [Uno.UI.sln](../../../../src/Uno.UI.sln) 3. Select the `Uno.UI` project 4. Build Inside Visual Studio, the number of platforms is restricted to limit the compilation time. -## Building Uno.UI for macOS using Visual Studio for Mac - -See [instructions here](building-uno-macos.md) for building Uno.UI for the macOS platform. - ## Troubleshooting build issues Here are some tips when building the Uno solution and failures happen: @@ -115,14 +111,14 @@ In order to update those reference assemblies, set ` ### Using the Package Diff tool -Refer to the [guidelines for breaking changes](../contributing/guidelines/breaking-changes.md) document. +Refer to the [guidelines for breaking changes](xref:Uno.Contributing.BreakingChanges) document. ### Updating the Nuget packages used by the Uno.UI solution -The versions used are centralized in the [Directory.Build.targets](https://github.com/unoplatform/uno/blob/master/src/Directory.Build.targets) file, and all the +The versions used are centralized in the [Directory.Build.targets](../../../../src/Directory.Build.targets) file, and all the locations where `` are used. -When updating the versions of NuGet packages, make sure to update all the .nuspec files in the [`build/nuget` folder](https://github.com/unoplatform/uno/tree/master/build/nuget). +When updating the versions of NuGet packages, make sure to update all the .nuspec files in the [`build/nuget` folder](../../../../build/nuget). ### Running the SyncGenerator tool @@ -135,8 +131,8 @@ The tool needs to be run on Windows because of its dependency on the Windows SDK To run the synchronization tool: - Open a `Developer Command Prompt for Visual Studio` (2019 or 2022) -- Go to the `uno\build` folder (not the `uno\src\build` folder) -- Run the `run-api-sync-tool.cmd` script; make sure to follow the instructions +- Run [`uno\build\run-api-sync-tool.cmd`](../../../../build/run-api-sync-tool.cmd) (! not the `uno\src\build` folder !) you can do so by following the link on this text. +- make sure to follow the instructions Note that the tool is manually run for the WinUI part of the build and automatically run as part of the CI during the UWP part of the build. diff --git a/doc/articles/contributing/guidelines/code-style.md b/doc/articles/contributing/guidelines/code-style.md index 8fe61c623662..0c6ea57df118 100644 --- a/doc/articles/contributing/guidelines/code-style.md +++ b/doc/articles/contributing/guidelines/code-style.md @@ -18,7 +18,7 @@ This section describes some recurring patterns and practices you'll see in Uno c ### Partial classes -[Partial class definitions](https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods) are used extensively in Uno. The two main use cases for partial classes are [platform-specific code](../../platform-specific-csharp.md) and [generated code](../../uno-development/uno-internals-overview.md#generated-notimplemented-stubs). +[Partial class definitions](https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods) are used extensively in Uno. The two main use cases for partial classes are [platform-specific code](../../platform-specific-csharp.md) and [generated code](xref:Uno.Contributing.Overviewmd#generated-notimplemented-stubs). However, in some cases where it makes sense, partial class files are also used for logical separation of code. If you're implementing a type that owns a lot of dependency properties, consider putting these in a separate partial, to avoid cluttering up the file where the actual business logic is with DP boilerplate. Another use case for a partial is a nested class with a large definition. @@ -26,13 +26,13 @@ However, in some cases where it makes sense, partial class files are also used f Uno uses lightweight `IDisposables` widely for robust lifetime management. The most commonly used types for this purpose are `SerialDisposable`, `CompositeDisposable`, `CancellationDisposable`, and `DisposableAction`. -If you've used the `Reactive Extensions` framework, these names [might be familiar](https://learn.microsoft.com/previous-versions/dotnet/reactive-extensions/hh229090(v=vs.103)), and in fact these disposables behave identically to their Rx equivalents. However, they've been transplanted into [Uno](https://github.com/unoplatform/uno/tree/master/src/Uno.Foundation/Uno.Core.Extensions/Uno.Core.Extensions.Disposables/Disposables), to avoid having to take a dependency on `System.Reactive`. +If you've used the `Reactive Extensions` framework, these names [might be familiar](https://learn.microsoft.com/previous-versions/dotnet/reactive-extensions/hh229090(v=vs.103)), and in fact these disposables behave identically to their Rx equivalents. However, they've been transplanted into [Uno](../../../../src/Uno.Foundation/Uno.Core.Extensions/Uno.Core.Extensions.Disposables/Disposables), to avoid having to take a dependency on `System.Reactive`. ### Extension methods [Extension methods](https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/extension-methods) are used throughout the Uno Platform codebase to add reusable functionality to existing types, particularly types coming from the Xamarin bindings. Extension methods should be defined in a dedicated class, with the naming convention `[TypeName]Extensions.cs`, where `TypeName` is the name of the type either being returned or passed as the `this` parameter. -A number of extensions to the standard .NET types already exists in [Uno.Foundation](https://github.com/unoplatform/uno/tree/master/src/Uno.Foundation/Uno.Core.Extensions). So, you should check those first to see if they do what you need. +A number of extensions to the standard .NET types already exists in [Uno.Foundation](../../../../src/Uno.Foundation/Uno.Core.Extensions). So, you should check those first to see if they do what you need. When adding a new extension method class, it should typically be marked `internal`, to avoid naming clashes with existing consumer code. diff --git a/doc/articles/uno-development/debugging-templates.md b/doc/articles/contributing/guidelines/debugging-templates.md similarity index 96% rename from doc/articles/uno-development/debugging-templates.md rename to doc/articles/contributing/guidelines/debugging-templates.md index 8d1a36d5591c..68cfd8f55570 100644 --- a/doc/articles/uno-development/debugging-templates.md +++ b/doc/articles/contributing/guidelines/debugging-templates.md @@ -17,7 +17,7 @@ Some of the templates are reusing the same sources. For example the full solutio To make modifications to those templates and test the result: -- In Visual Studio, open the solution using the [Uno.UI-SolutionTemplates.slnf](building-uno-ui.md) filter +- In Visual Studio, open the solution using the [Uno.UI-SolutionTemplates.slnf](xref:Uno.Contributing.BuildingUno) filter - Right click on the `Uno.ProjectTemplates.Dotnet` project, select `Pack` - This will create a `Uno.ProjectTemplates.Dotnet.255.255.255.255.nupkg` file - Install this file using `dotnet new -i C:\[your_path]\bin\Debug\Uno.ProjectTemplates.Dotnet.255.255.255.255.nupkg` diff --git a/doc/articles/uno-development/debugging-uno-ui.md b/doc/articles/contributing/guidelines/debugging-uno-ui.md similarity index 95% rename from doc/articles/uno-development/debugging-uno-ui.md rename to doc/articles/contributing/guidelines/debugging-uno-ui.md index 08dec524ee98..1479845d3618 100644 --- a/doc/articles/uno-development/debugging-uno-ui.md +++ b/doc/articles/contributing/guidelines/debugging-uno-ui.md @@ -7,7 +7,7 @@ uid: Uno.Contributing.DebuggingUno > [!NOTE] > [Find instructions for building the Uno.UI solution here.](xref:Uno.Contributing.BuildingUno) -## Debugging Uno.UI samples +## Debugging Uno.UI samples To debug the **SamplesApp** in the Uno.UI solution, which includes an extensive set of samples and test cases for the controls supported by Uno.UI, as well as non-UI features: @@ -18,7 +18,7 @@ To debug the **SamplesApp** in the Uno.UI solution, which includes an extensive 3. Set `SamplesApp.[TargetPlatform]` as the selected Startup Project. 4. Launch the samples app from Visual Studio. -See [this article](working-with-the-samples-apps.md) for more information on working with the SamplesApp and authoring new samples. +See [this article](xref:Uno.Contributing.SamplesApp) for more information on working with the SamplesApp and authoring new samples. ## Debugging Uno in another application @@ -46,7 +46,7 @@ Then, here are the steps to use a local build of Uno.WinUI in another applicatio To debug Uno.UI code in the application, follow these steps (using `FrameworkElement.MeasureOverride()` as an example): -1. Open [`FrameworkElement.cs`](https://github.com/unoplatform/uno/blob/master/src/Uno.UI/UI/Xaml/FrameworkElement.cs) in the Uno.UI solution. +1. Open [`FrameworkElement.cs`](../../../../src/Uno.UI/UI/Xaml/FrameworkElement.cs) in the Uno.UI solution. 2. Right-click on the `FrameworkElement.cs` tab header in Visual Studio and choose 'Copy Full Path'. 3. Switch to the Visual Studio instance where your application is open. 4. In your application solution, choose File->Open->File... or simply `Ctrl+O`, paste the path to `FrameworkElement.cs` into the file open dialog, and open `FrameworkElement.cs` in the application solution. diff --git a/doc/articles/contributing/guidelines/implementing-a-new-winui-winrt-feature.md b/doc/articles/contributing/guidelines/implementing-new-winui-winrt-api.md similarity index 95% rename from doc/articles/contributing/guidelines/implementing-a-new-winui-winrt-feature.md rename to doc/articles/contributing/guidelines/implementing-new-winui-winrt-api.md index 324e6b06c4c9..b223237da189 100644 --- a/doc/articles/contributing/guidelines/implementing-a-new-winui-winrt-feature.md +++ b/doc/articles/contributing/guidelines/implementing-new-winui-winrt-api.md @@ -1,5 +1,5 @@ --- -uid: Uno.Contributing.ImplementWinUIWinRTAPI +uid: Uno.Contributing.ImplementWinUIWinRT-API --- # Guidelines for implementing a new WinUI/WinRT API @@ -36,6 +36,6 @@ If your API implementation is for a specific platform: when implemented for Android only. -When implementing a feature, try to place as much code as possible in a common source file (a non-suffixed file), so that it is reused across platforms. Make sure to follow [partial classes coding guidelines](code-style.md). +When implementing a feature, try to place as much code as possible in a common source file (a non-suffixed file), so that it is reused across platforms. Make sure to follow [partial classes coding guidelines](xref:Uno.Contributing.CodeStyle). Note that the generated files may be overridden at any point, and placing custom code (aside from changing the `NotImplemented` values) will be overwritten. diff --git a/doc/articles/uno-development/release-procedure.md b/doc/articles/contributing/guidelines/release-procedure.md similarity index 100% rename from doc/articles/uno-development/release-procedure.md rename to doc/articles/contributing/guidelines/release-procedure.md diff --git a/doc/articles/contributing/guidelines/updating-dependencies.md b/doc/articles/contributing/guidelines/updating-dependencies.md index 1290851add38..94ea7c9c97f7 100644 --- a/doc/articles/contributing/guidelines/updating-dependencies.md +++ b/doc/articles/contributing/guidelines/updating-dependencies.md @@ -22,7 +22,7 @@ The following dependencies don't change the public API surface and are typically - Moq The following dependencies require manual adjustments before merging: - + - [docfx.console](https://github.com/unoplatform/Uno/pull/1082/commits/c222caf8c23b35e19f6b33cd624cbfa714250bfe) - `Microsoft.CodeAnalysis.*`. Those dependencies need to be aligned with the source generation task package, for which the dependency cannot be be explicitly provided. - `Xamarin.GooglePlayServices.*`. Those dependencies are added per TargetFramework (Android SDK version), not updated. diff --git a/doc/articles/uno-development/listviewbase-internals.md b/doc/articles/contributing/listviewbase-internals.md similarity index 98% rename from doc/articles/uno-development/listviewbase-internals.md rename to doc/articles/contributing/listviewbase-internals.md index 13b8221e3f09..34f64737b956 100644 --- a/doc/articles/uno-development/listviewbase-internals.md +++ b/doc/articles/contributing/listviewbase-internals.md @@ -6,7 +6,7 @@ uid: Uno.Contributing.ListViewBase This document describes the internal operations of Uno's `ListViewBase` implementation(s) in detail, aimed at contributors. -Before reading it, you should first read the documentation of [ListViewBase aimed at Uno app developers](../controls/ListViewBase.md), which covers the high-level differences between Uno's implementation and UWP's implementation. +Before reading it, you should first read the documentation of [ListViewBase aimed at Uno app developers](xref:Uno.Controls.ListViewBase), which covers the high-level differences between Uno's implementation and UWP's implementation. ## Introduction @@ -48,7 +48,7 @@ Architecturally, the Android and iOS implementations share a similar high-level (As an aside, this division of labor has no equivalent in `ListView`, but a somewhat similar approach is taken by WinUI's newer [`ItemsRepeater`](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.itemsrepeater) control, also available in Uno.) -[This diagram](../controls/ListViewBase.md#difference-in-the-visual-tree) shows how the `NativeListViewBase` view is incorporated into the visual tree, and the resulting difference from UWP. The key differences are: +[This diagram](xref:Uno.Controls.ListViewBase#difference-in-the-visual-tree) shows how the `NativeListViewBase` view is incorporated into the visual tree, and the resulting difference from UWP. The key differences are: - the scrolling container is the `NativeListViewBase` itself, not the `ScrollViewer`. Thus the `ItemsPresenter` is **outside** the scrollable region. Additionally, there's no ScrollContentPresenter; instead there's a ListViewBaseScrollContentPresenter. (It was implemented this way back when ScrollContentPresenter inherited directly from the native scroll container.) - the `ItemsStackPanel` (or `ItemsWrapGrid`) is not actually present in the visual tree. These items panels are created, and their configured values (eg `Orientation`) are used to set the behavior of the list, but they are not actually loaded into the visual hierarchy or measured and arranged. They just act as a facade for the native layouter. diff --git a/doc/articles/uno-development/creating-mocked-tests.md b/doc/articles/contributing/tests/creating-mocked-tests.md similarity index 92% rename from doc/articles/uno-development/creating-mocked-tests.md rename to doc/articles/contributing/tests/creating-mocked-tests.md index 504e4cf960a0..5c88b636bad7 100644 --- a/doc/articles/uno-development/creating-mocked-tests.md +++ b/doc/articles/contributing/tests/creating-mocked-tests.md @@ -1,5 +1,5 @@ --- -uid: Uno.Contributing.CreateMockedTests +uid: Uno.Contributing.Tests.CreateMockedTests --- # Creating unit tests in Uno.UI.Tests @@ -10,7 +10,7 @@ Adding tests here is closest to the 'traditional' unit test experience: you can ## Running tests in Uno.UI.Tests -1. Open and build the Uno.UI solution [for the unit tests target](building-uno-ui.md). +1. Open and build the Uno.UI solution [for the unit tests target](xref:Uno.Contributing.BuildingUno). 2. Open Test Explorer from the TEST menu. 3. Tests are listed under `Uno.UI.Tests`. You can run all tests or a subsection, with or without debugging. Tests run in a vanilla .NET Framework environment. (Note: You usually don't need to run `Uno.Xaml.Tests` tests locally, unless you're making changes to low-level XAML parsing in `Uno.Xaml`. ) @@ -19,4 +19,4 @@ Adding tests here is closest to the 'traditional' unit test experience: you can 1. Locate the test class corresponding to the control or class you want to create a test for. If you need to add a new test class, create the file as `Namespace_In_Snake_Case/ControlNameTests/Given_ControlName.cs`. be marked with the `[TestClass]` attribute. 2. Add tests for your cases, naming it as `When_Your_Scenario` and marking it with the `[TestMethod]` attribute. (For more information about the 'Given-When-Then' naming style, read ) -The mocking layer of Uno.UI for unit tests has been added as needed, and depending on your case, you may encounter areas of functionality that aren't supported. Your options if that happens are either to add the missing mocking, or to [add the test in Uno.UI.RuntimeTests](creating-runtime-tests.md) instead. +The mocking layer of Uno.UI for unit tests has been added as needed, and depending on your case, you may encounter areas of functionality that aren't supported. Your options if that happens are either to add the missing mocking, or to [add the test in Uno.UI.RuntimeTests](xref:Uno.Contributing.Tests.RuntimeTests) instead. diff --git a/doc/articles/contributing/tests/creating-ps-pester-tests.md b/doc/articles/contributing/tests/creating-ps-pester-tests.md new file mode 100644 index 000000000000..e44f129265ad --- /dev/null +++ b/doc/articles/contributing/tests/creating-ps-pester-tests.md @@ -0,0 +1,26 @@ +--- +uid: Uno.Contributing.Tests.PowerShell-Pester-Tests +--- + +# Testing PowerShell Scripts with Pester + +## Introduction + +Some Parts of Uno.UI like the [Toc Checker](xref:Uno.Contributing.check-toc.Overview) with its [Utility Functions](xref:Uno.Contributing.check-toc.Utilities) are written in PowerShell. To make sure they are working properly, the recommended and most commonly used Testing Framework is [Pester](https://pester.dev/docs/quick-start). + + + + + + +## Showing Pester Test Result in CI + +Pester integrates seamlessly with CI pipelines, allowing you to automate the validation of your PowerShell scripts. By including Pester tests in your CI configuration, you can ensure that changes to the `check_toc.ps1` script or its utilities do not introduce regressions. Most CI systems, such as GitHub Actions or Azure Pipelines, support running Pester tests and can display detailed test results in their interfaces. + +For more information, refer to the [Pester Test Results Documentation](https://pester.dev/docs/usage/test-results). + +## 📄 Related Pages + +- [The Uno docs website and DocFX](xref:Uno.Contributing.DocFx) +- [Validating the Table of Contents](xref:Uno.Contributing.check-toc.Overview) +- [Utility Functions for `check_toc`](xref:Uno.Contributing.check-toc.Utilities) diff --git a/doc/articles/uno-development/creating-runtime-tests.md b/doc/articles/contributing/tests/creating-runtime-tests.md similarity index 98% rename from doc/articles/uno-development/creating-runtime-tests.md rename to doc/articles/contributing/tests/creating-runtime-tests.md index 6d775c66be92..333cb53b8a20 100644 --- a/doc/articles/uno-development/creating-runtime-tests.md +++ b/doc/articles/contributing/tests/creating-runtime-tests.md @@ -1,5 +1,5 @@ --- -uid: Uno.Contributing.CreateRuntimeTests +uid: Uno.Contributing.Tests.CreateRuntimeTests --- # Creating unit tests in Uno.UI.RuntimeTests @@ -8,13 +8,13 @@ Platform-runtime unit tests are relatively cheap (in terms of developer producti Tests in Uno.UI.RuntimeTests are easy to write. There are a few special attributes and environmental helpers to know about, which this guide will cover. -For other types of automated tests used internally by Uno.UI, [see here](../contributing/guidelines/creating-tests.md). +For other types of automated tests used internally by Uno.UI, [see here](xref:Uno.Contributing.Tests.CreatingTests). ## Running tests locally Since the Uno.UI.RuntimeTests tests run in the platform environment using the real Uno.UI binaries, they must be run from within SamplesApp. -1. Build and launch the SamplesApp, following [the instructions here](working-with-the-samples-apps.md). Note: if you're testing a mobile platform, it's recommended to run on a tablet in landscape mode. On a phone-sized layout, a few tests will fail because they don't have enough space to measure properly. +1. Build and launch the SamplesApp, following [the instructions here](xref:Uno.Contributing.SamplesApp). Note: if you're testing a mobile platform, it's recommended to run on a tablet in landscape mode. On a phone-sized layout, a few tests will fail because they don't have enough space to measure properly. 2. From the sample menu, navigate to 'Unit Tests' > 'Unit Tests Runner' or click on the top-left-most button. 3. (Optional) Add a filter string in the text input control at the top of the page (for example the name or part of the name of your test method); only tests matching the filter will be run. Otherwise, all tests will run. > On mobile devices with limit screen width, you can drag the grid-slitter (the horizontal and vertical blue bars) to make more space for the filter textbox or test area. diff --git a/doc/articles/contributing/guidelines/creating-tests.md b/doc/articles/contributing/tests/creating-tests.md similarity index 82% rename from doc/articles/contributing/guidelines/creating-tests.md rename to doc/articles/contributing/tests/creating-tests.md index 11b1c3ca5584..b63b1340ba8c 100644 --- a/doc/articles/contributing/guidelines/creating-tests.md +++ b/doc/articles/contributing/tests/creating-tests.md @@ -1,5 +1,5 @@ --- -uid: Uno.Contributing.CreatingTests +uid: Uno.Contributing.Tests.CreatingTests --- # Guidelines for creating tests @@ -12,9 +12,9 @@ This guide offers an overview of the various types of tests used within Uno, and The 'TLDR' rule of thumb for adding tests is: -- if you're testing platform-independent functionality, like the dependency property system, [use Uno.UI.Tests](../../uno-development/creating-mocked-tests.md); -- if you're testing platform-dependent functionality that can be verified programmatically in-process, like checking that a control is measured and arranged properly, [use Uno.UI.RuntimeTests](../../uno-development/creating-runtime-tests.md); -- if your test needs to simulate user interaction or check that the final screen output is correct, [use SamplesApp.UITests](../../uno-development/creating-ui-tests.md). +- if you're testing platform-independent functionality, like the dependency property system, [use Uno.UI.Tests](xref:Uno.Contributing.Tests.CreateMockedTests); +- if you're testing platform-dependent functionality that can be verified programmatically in-process, like checking that a control is measured and arranged properly, [use Uno.UI.RuntimeTests](xref:Uno.Contributing.Tests.CreateRuntimeTests); +- if your test needs to simulate user interaction or check that the final screen output is correct, [use SamplesApp.UITests](xref:Uno.Contributing.Tests.CreateUITests). ## Types of tests @@ -47,7 +47,7 @@ They can verify assertions about the state of the app: - onscreen bounds of a view element - comparing screenshots at different stages of the app, and asserting equality or inequality -A complete set of instructions for authoring UI tests is available in [Using the SamplesApp documentation](../../uno-development/working-with-the-samples-apps.md). +A complete set of instructions for authoring UI tests is available in [Using the SamplesApp documentation](xref:Uno.Contributing.SamplesApp). Although only a subset of the samples in the SamplesApp are covered by automated UI tests, _all_ samples are screen-shotted on every build, and a reporting tool (runs on Skia, Wasm, Android, and iOS) reports any screenshots that differ from the previous build. Currently, the build isn't gated on these checks, but this may be adjusted in the future. @@ -70,23 +70,23 @@ The platform runtime tests also have access to internal Uno.UI members if need b ### XAML code generation tests (`XamlGenerationTests`) -These specifically target [the parser](https://github.com/unoplatform/uno/tree/master/src/SourceGenerators/Uno.UI.SourceGenerators/XamlGenerator) which generates C# code from XAML files. They are 'tests' in a simple sense that if the parser throws an error, or if it generates invalid C# code, they will fail the CI build. +These specifically target [the parser](../../../../src/SourceGenerators/Uno.UI.SourceGenerators/XamlGenerator) which generates C# code from XAML files. They are 'tests' in a simple sense that if the parser throws an error, or if it generates invalid C# code, they will fail the CI build. If you want to actually test that generated XAML produces correct behavior, which will be the case most of the time, you should use one of the other test types. ### Source generator tests -These can be used to assert that a given input to a given source generator produces specific expected diagnostics. The infrastructure for the tests easily allows to test the generator output exactly, but you should avoid that kind of assertion if you can. These tests exist in [`Uno.UI.SourceGenerators.Tests`](https://github.com/unoplatform/uno/tree/master/src/SourceGenerators/Uno.UI.SourceGenerators.Tests). +These can be used to assert that a given input to a given source generator produces specific expected diagnostics. The infrastructure for the tests easily allows to test the generator output exactly, but you should avoid that kind of assertion if you can. These tests exist in [`Uno.UI.SourceGenerators.Tests`](../../../../src/SourceGenerators/Uno.UI.SourceGenerators.Tests). ### UI snapshot tests -These are 'semi-automated' tests that takes a screenshot of each sample in the [SamplesApp](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared). +These are 'semi-automated' tests that takes a screenshot of each sample in the [SamplesApp](../../../../src/SamplesApp/UITests.Shared). -On Android, iOS, and Wasm, a minimal UI test is [generated](https://github.com/unoplatform/uno/blob/master/src/SamplesApp/SamplesApp.UITests.Generator/SnapShotTestGenerator.cs) which simply runs the sample (which automatically takes a screenshot of the loaded sample). +On Android, iOS, and Wasm, a minimal UI test is [generated](../../../../src/SamplesApp/SamplesApp.UITests.Generator/SnapShotTestGenerator.cs) which simply runs the sample (which automatically takes a screenshot of the loaded sample). On Skia and macOS, we [loop over the samples and load them](https://github.com/unoplatform/uno/blob/b1a6eddcad3bcca6d9756b0a57ff6cf458321048/src/SamplesApp/SamplesApp.UnitTests.Shared/Controls/UITests/Presentation/SampleChooserViewModel.cs#L364-L427), then [save a screenshot](https://github.com/unoplatform/uno/blob/b1a6eddcad3bcca6d9756b0a57ff6cf458321048/src/SamplesApp/SamplesApp.UnitTests.Shared/Controls/UITests/Presentation/SampleChooserViewModel.cs#L1221-L1244) of each sample using `RenderTargetBitmap` and `BitmapEncoder`. This is generally faster than relying on UI tests. -The screenshots from each sample, as well as all screenshots generated by the main UI tests (using the `TakeScreenshot()` method), are [compared](https://github.com/unoplatform/uno/tree/master/src/Uno.UI.TestComparer) with the same sample from the most recent merged CI build. +The screenshots from each sample, as well as all screenshots generated by the main UI tests (using the `TakeScreenshot()` method), are [compared](../../../../src/Uno.UI.TestComparer) with the same sample from the most recent merged CI build. **Failed** comparisons will not fail the build (for one thing, it's possible the differences are expected or even desired). Instead, a report is generated, with a summary added to the PR as a comment listing all samples that changed. The onus is on the PR author to manually review these changes to ensure that no regressions have been introduced. @@ -132,6 +132,7 @@ As a rule of thumb, if the behavior you're testing can be verified by a unit tes If you're fixing a bug that can be verified by a static sample, create a SamplesApp sample that can be monitored by the snapshot comparer. If you're fixing a bug that involves user interaction or multiple asynchronous UI operations, or you want a hard verification of the onscreen visual state, then create a UI test. + ## What can't be tested? @@ -139,4 +140,4 @@ Some UI behaviors are difficult to test in an automated fashion, such as transie Some non-UI APIs may not be testable in the emulated environment on the CI build. -If you're working on something that falls under one of these descriptions, you should add a [sample](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared) that covers the bug or feature you're working on, and verify that the existing samples in the same feature category aren't negatively affected by your changes. Also, you should mark such sample as a manual test. For more information about manual tests, see [Adding a manual test sample section in Using the SamplesApp documentation](../../uno-development/working-with-the-samples-apps.md#adding-a-manual-test-sample). +If you're working on something that falls under one of these descriptions, you should add a [sample](../../../../src/SamplesApp/UITests.Shared) that covers the bug or feature you're working on, and verify that the existing samples in the same feature category aren't negatively affected by your changes. Also, you should mark such sample as a manual test. For more information about manual tests, see [Adding a manual test sample section in Using the SamplesApp documentation](xref:Uno.Contributing.SamplesApp#adding-a-manual-test-sample). diff --git a/doc/articles/uno-development/creating-ui-tests.md b/doc/articles/contributing/tests/creating-ui-tests.md similarity index 87% rename from doc/articles/uno-development/creating-ui-tests.md rename to doc/articles/contributing/tests/creating-ui-tests.md index 00e51731c437..982746c4bf32 100644 --- a/doc/articles/uno-development/creating-ui-tests.md +++ b/doc/articles/contributing/tests/creating-ui-tests.md @@ -16,19 +16,19 @@ UI tests contribute significantly to the CI build time, and for many purposes a - you can put the app in the required state programmatically, and - you can verify the correct behavior programmatically (eg by checking DesiredSize, ActualWidth/ActualHeight etc). - For more on general testing strategy in Uno.UI, see [Guidelines for creating tests](../contributing/guidelines/creating-tests.md). + For more on general testing strategy in Uno.UI, see [Guidelines for creating tests](xref:Uno.Contributing.Tests.CreatingTests). > [!NOTE] -> [Platform runtime unit tests](../contributing/guidelines/creating-tests.md) are generally preferred to UI tests as their execution performance is generally faster than UI Tests. +> [Platform runtime unit tests](xref:Uno.Contributing.Tests.CreatingTests) are generally preferred to UI tests as their execution performance is generally faster than UI Tests. ## Running UI tests locally 1. Ensure [your environment is configured](xref:Uno.GetStarted.vs2022) for the platform you want to run on. 1. Ensure `UnoTargetFrameworkOverride` is set to `net7.0-android` for testing on Android, `net7.0-ios` for testing on iOS, and `net7.0` for testing on Wasm. -1. Open Uno.UI with the [correct target override and solution filter](building-uno-ui.md) for the platform you want to run on. -1. [Build and run the SamplesApp](working-with-the-samples-apps.md) at least once. +1. Open Uno.UI with the [correct target override and solution filter](xref:Uno.Contributing.BuildingUno) for the platform you want to run on. +1. [Build and run the SamplesApp](xref:Uno.Contributing.SamplesApp) at least once. 1. Only Android and WASM are supported from Visual Studio for Windows. (Running tests on iOS using a Mac is possible, see additional instructions below.) -1. If testing on WebAssembly, ensure that [`WebAssemblyDefaultUri`](https://github.com/unoplatform/uno/blob/master/src/SamplesApp/SamplesApp.UITests/Constants.cs) matches Url used when the sample app was launched in the step above. Visual Studio may change the Url on demand to avoid conflicts with already running sites on the same machine. +1. If testing on WebAssembly, ensure that [`WebAssemblyDefaultUri`](../../../../src/SamplesApp/SamplesApp.UITests/Constants.cs) matches Url used when the sample app was launched in the step above. Visual Studio may change the Url on demand to avoid conflicts with already running sites on the same machine. 1. Open the [Test Explorer](https://learn.microsoft.com/visualstudio/test/run-unit-tests-with-test-explorer) in Visual Studio. 1. UI tests are grouped under 'SamplesApp.UITests'. From the Test Explorer you can run all tests, debug a single test, etc. @@ -47,8 +47,8 @@ UI tests contribute significantly to the CI build time, and for many purposes a ## Adding a new test -1. Typically the first step is to [add a sample to the SamplesApp](working-with-the-samples-apps.md) that reproduces the bug you're fixing or demonstrates the functionality you're adding, unless you can do so with an existing sample. -2. The UI test fixtures themselves are located in [SamplesApp.UITests](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/SamplesApp.UITests). Locate the test class corresponding to the control or class you want to create a test for. If you need to add a new test class, create the file as `Namespace_In_Snake_Case/ControlNameTests/ControlName_Tests.cs`. The class should inherit from `SampleControlUITestBase` and be marked with the `[TestFixture]` attribute. +1. Typically the first step is to [add a sample to the SamplesApp](xref:Uno.Contributing.SamplesApp) that reproduces the bug you're fixing or demonstrates the functionality you're adding, unless you can do so with an existing sample. +2. The UI test fixtures themselves are located in [SamplesApp.UITests](../../../../src/SamplesApp/SamplesApp.UITests). Locate the test class corresponding to the control or class you want to create a test for. If you need to add a new test class, create the file as `Namespace_In_Snake_Case/ControlNameTests/ControlName_Tests.cs`. The class should inherit from `SampleControlUITestBase` and be marked with the `[TestFixture]` attribute. 3. Add your test, making sure to include the `[Test]` and `[AutoRetry]` attributes. (The `[AutoRetry]` attributes indicates that the test should be retried if it fails. Currently it's required for all tests.) ## Selectively ignore tests per platform diff --git a/doc/articles/uno-development/themeresource-internals.md b/doc/articles/contributing/themeresource-internals.md similarity index 97% rename from doc/articles/uno-development/themeresource-internals.md rename to doc/articles/contributing/themeresource-internals.md index a029e2a90e74..95996c9c7dad 100644 --- a/doc/articles/uno-development/themeresource-internals.md +++ b/doc/articles/contributing/themeresource-internals.md @@ -41,7 +41,7 @@ The resource update machinery can be broadly split into two parts: registering r ### Registering assignations for updates -ThemeResource assignments can only be created in XAML - WinUI provides no way to create them in code. Thus, in Uno, all assignations come ultimately from either [XamlFileGenerator](https://github.com/unoplatform/uno/blob/master/src/SourceGenerators/Uno.UI.SourceGenerators/XamlGenerator/XamlFileGenerator.cs) or XamlReader/[XamlObjectBuilder](https://github.com/unoplatform/uno/blob/master/src/Uno.UI/UI/Xaml/Markup/Reader/XamlObjectBuilder.cs). +ThemeResource assignments can only be created in XAML - WinUI provides no way to create them in code. Thus, in Uno, all assignations come ultimately from either [XamlFileGenerator](../../../src/SourceGenerators/Uno.UI.SourceGenerators/XamlGenerator/XamlFileGenerator.cs) or XamlReader/[XamlObjectBuilder](../../../src/Uno.UI/UI/Xaml/Markup/Reader/XamlObjectBuilder.cs). There are 3 cases for ThemeResource assignations that are handled differently: diff --git a/doc/articles/uno-development/uno-internals-android.md b/doc/articles/contributing/uno-internals-android.md similarity index 87% rename from doc/articles/uno-development/uno-internals-android.md rename to doc/articles/contributing/uno-internals-android.md index 4978b6febf91..5c17f23c4919 100644 --- a/doc/articles/uno-development/uno-internals-android.md +++ b/doc/articles/contributing/uno-internals-android.md @@ -4,13 +4,13 @@ uid: Uno.Contributing.Android # How Uno works on Android -This article explores Android-specific details of Uno's internals, with a focus on information that's useful for contributors to Uno. For an overview of how Uno works on all platforms, see [this article](uno-internals-overview.md). +This article explores Android-specific details of Uno's internals, with a focus on information that's useful for contributors to Uno. For an overview of how Uno works on all platforms, see [this article](xref:Uno.Contributing.Overview). Some particulars of Android: ## Some classes are written in Java -Several base classes and helper classes are written in native Java code. These are located in [Uno.UI.BindingHelper.Android](https://github.com/unoplatform/uno/tree/master/src/Uno.UI.BindingHelper.Android/Uno/UI). +Several base classes and helper classes are written in native Java code. These are located in [Uno.UI.BindingHelper.Android](../../../src/Uno.UI.BindingHelper.Android/Uno/UI). The Xamarin.Android framework gives complete access to the Android API from managed C#, so why write anything in Java? The reason is performance. The interop between Java and C# can be costly, and instrumented profiling identified that certain virtual methods when overridden in C# and called in heavily-used paths (eg measure and arrange) imposed a measurable performance penalty. Over time, these 'hot' methods have been lowered to Java classes, particularly the `UnoViewGroup` class. @@ -25,4 +25,4 @@ Recall that `UIElement` implements `DependencyObect` [as an interface](uno-inter ## Layouting -Uno's measure and arrange logic is triggered from the native Android layout cycle. For a schematic of the control flow, see [Layouting in Android](Uno-UI-Layouting-Android.md). +Uno's measure and arrange logic is triggered from the native Android layout cycle. For a schematic of the control flow, see [Layouting in Android](xref:Uno.Contributing.LayoutingAndroid). diff --git a/doc/articles/uno-development/uno-internals-hotreload.md b/doc/articles/contributing/uno-internals-hotreload.md similarity index 100% rename from doc/articles/uno-development/uno-internals-hotreload.md rename to doc/articles/contributing/uno-internals-hotreload.md diff --git a/doc/articles/uno-development/uno-internals-ios.md b/doc/articles/contributing/uno-internals-ios.md similarity index 84% rename from doc/articles/uno-development/uno-internals-ios.md rename to doc/articles/contributing/uno-internals-ios.md index 8495d9e8c9a6..97cc481b918c 100644 --- a/doc/articles/uno-development/uno-internals-ios.md +++ b/doc/articles/contributing/uno-internals-ios.md @@ -4,15 +4,15 @@ uid: Uno.Contributing.iOS # How Uno works on iOS -This article explores iOS-specific details of Uno's internals, with a focus on information that's useful for contributors to Uno. For an overview of how Uno works on all platforms, see [this article](uno-internals-overview.md). +This article explores iOS-specific details of Uno's internals, with a focus on information that's useful for contributors to Uno. For an overview of how Uno works on all platforms, see [this article](xref:Uno.Contributing.Overview). ## UIElement inherits from UIView `UIElement` in Uno is a native view on iOS, inheriting from the general `UIView` type. To elaborate, `UIElement`'s base classes are the following: `UIKit.UIView` → `Uno.UI.Controls.BindableUIView` → `Windows.UI.Xaml.UIElement` -Recall that `UIElement` implements `DependencyObject` [as an interface](uno-internals-overview.md) in Uno. +Recall that `UIElement` implements `DependencyObject` [as an interface](xref:Uno.Contributing.Overview) in Uno. ## Layouting -Uno's measure and arrange logic is triggered from the native iOS layout cycle. For a schematic of the control flow, see [Layouting in iOS](Uno-UI-Layouting-iOS.md). +Uno's measure and arrange logic is triggered from the native iOS layout cycle. For a schematic of the control flow, see [Layouting in iOS](xref:Uno.Contributing.LayoutingiOS). diff --git a/doc/articles/uno-development/uno-internals-macos.md b/doc/articles/contributing/uno-internals-macos.md similarity index 93% rename from doc/articles/uno-development/uno-internals-macos.md rename to doc/articles/contributing/uno-internals-macos.md index 255a8cad6ff5..ac3ec6e05115 100644 --- a/doc/articles/uno-development/uno-internals-macos.md +++ b/doc/articles/contributing/uno-internals-macos.md @@ -4,14 +4,14 @@ uid: Uno.Contributing.macOS # How Uno works on macOS -This article explores macOS-specific details of Uno's internals, with a focus on information that's useful for contributors to Uno. For an overview of how Uno works on all platforms, see [this article](uno-internals-overview.md). +This article explores macOS-specific details of Uno's internals, with a focus on information that's useful for contributors to Uno. For an overview of how Uno works on all platforms, see [this article](xref:Uno.Contributing.Overview). ## UIElement inherits from NSView `UIElement` in Uno is a native view on macOS, inheriting from the general `NSView` type. To elaborate, `UIElement`'s base classes are the following: `AppKit.NSView` → `Uno.UI.Controls.BindableNSView` → `Windows.UI.Xaml.UIElement` -Recall that `UIElement` implements `DependencyObect` [as an interface](uno-internals-overview.md) in Uno. +Recall that `UIElement` implements `DependencyObect` [as an interface](xref:Uno.Contributing.Overview) in Uno. ## Similarities with iOS diff --git a/doc/articles/uno-development/uno-internals-overview.md b/doc/articles/contributing/uno-internals-overview.md similarity index 74% rename from doc/articles/uno-development/uno-internals-overview.md rename to doc/articles/contributing/uno-internals-overview.md index a854d9ac89db..9b7b2dcc313e 100644 --- a/doc/articles/uno-development/uno-internals-overview.md +++ b/doc/articles/contributing/uno-internals-overview.md @@ -34,7 +34,7 @@ APIs for non-UI features, for example [`Windows.System.Power`](../features/windo ### Generated `NotImplemented` stubs -WinUI has a very large API surface area, and not all features in it have been implemented by Uno Platform. We want pre-existing WinUI (and UWP) apps and libraries that reference these features to still be able to at least compile on Uno Platform. To support this, an [internal automated tool](https://github.com/unoplatform/uno/tree/master/src/Uno.UWPSyncGenerator) inspects the UWP framework, compares it to authored code in Uno Platform, and generates stubs for all types and type members that exist in UWP but are not implemented on Uno. For example: +WinUI has a very large API surface area, and not all features in it have been implemented by Uno Platform. We want pre-existing WinUI (and UWP) apps and libraries that reference these features to still be able to at least compile on Uno Platform. To support this, an [internal automated tool](../../../src/Uno.UWPSyncGenerator) inspects the UWP framework, compares it to authored code in Uno Platform, and generates stubs for all types and type members that exist in UWP but are not implemented on Uno. For example: ```csharp #if __ANDROID__ || __IOS__ || __TVOS__ || IS_UNIT_TESTS || __WASM__ @@ -59,9 +59,10 @@ Notice the platform conditionals, since a member may be implemented for some pla For more details on how Uno Platform runs on each platform, see platform-specific information for: -* [Android](uno-internals-android.md) -* [iOS](uno-internals-ios.md) -* [WebAssembly](uno-internals-wasm.md) +* [Android](xref:Uno.Contributing.Android) +* [iOS](xref:Uno.Contributing.iOS) +* [WebAssembly](xref:Uno.Contributing.Wasm) +* [macOS](xref:Uno.Contributing.macOS) ## Uno.WinUI build-time tooling @@ -69,18 +70,18 @@ For more details on how Uno Platform runs on each platform, see platform-specifi This is the most substantial compile-time task that Uno Platform carries out. Whenever an app or class library is built, all contained XAML files are parsed and converted to C# files, which are then compiled in the usual way. (Note that this differs from WinUI, which parses XAML to XAML Binary Format (.xbf) files which are processed by the WinUI runtime.) -Uno Platform uses existing libraries to parse a given XAML file into a XAML object tree, then Uno-specific code is responsible for interpreting the XAML object tree as a tree of visual elements and their properties. Most of this takes place within the [`XamlFileGenerator`](https://github.com/unoplatform/uno/blob/master/src/SourceGenerators/Uno.UI.SourceGenerators/XamlGenerator/XamlFileGenerator.cs) class. +Uno Platform uses existing libraries to parse a given XAML file into a XAML object tree, then Uno-specific code is responsible for interpreting the XAML object tree as a tree of visual elements and their properties. Most of this takes place within the [`XamlFileGenerator`](../../../src/SourceGenerators/Uno.UI.SourceGenerators/XamlGenerator/XamlFileGenerator.cs) class. ### DependencyObject implementation generator -On [Android](uno-internals-android.md), [iOS](uno-internals-ios.md), and [macOS](uno-internals-macos.md), `UIElement` (the base view type in UWP/WinUI) inherits from the native view class on the respective platform. This poses a challenge because `UIElement` inherits from the `DependencyObject` class in UWP/WinUI, which is a key part of the dependency property system. Uno makes this work by breaking from UWP/WinUI and having `DependencyObject` be an interface rather than a type. +On [Android](xref:Uno.Contributing.Android), [iOS](xref:Uno.Contributing.iOS), and [macOS](xref:Uno.Contributing.macOS), `UIElement` (the base view type in UWP/WinUI) inherits from the native view class on the respective platform. This poses a challenge because `UIElement` inherits from the `DependencyObject` class in UWP/WinUI, which is a key part of the dependency property system. Uno makes this work by breaking from UWP/WinUI and having `DependencyObject` be an interface rather than a type. -Class library authors and app authors sometimes inherit directly from `DependencyObject` rather than a more derived type. To support this scenario seamlessly, the [`DependencyObjectGenerator` task](https://github.com/unoplatform/uno/blob/master/src/SourceGenerators/Uno.UI.SourceGenerators/DependencyObject/DependencyObjectGenerator.cs) looks for such classes and [generates](https://github.com/unoplatform/Uno.SourceGeneration) a partial implementation for the `DependencyObject` interface, ie the methods that on UWP would be inherited from the base class. +Class library authors and app authors sometimes inherit directly from `DependencyObject` rather than a more derived type. To support this scenario seamlessly, the [`DependencyObjectGenerator` task](../../../src/SourceGenerators/Uno.UI.SourceGenerators/DependencyObject/DependencyObjectGenerator.cs) looks for such classes and [generates](https://github.com/unoplatform/Uno.SourceGeneration) a partial implementation for the `DependencyObject` interface, ie the methods that on UWP would be inherited from the base class. ### Formatting image assets -Different platforms have different requirements for where bundled image files are located and how multiple versions of the same asset are handled (eg, to target different resolutions). The [asset retargeting task](https://github.com/unoplatform/uno/blob/master/src/SourceGenerators/Uno.UI.Tasks/Assets/RetargetAssets.cs) copies the image assets located in the shared project to the appropriate location and format for the target platform. +Different platforms have different requirements for where bundled image files are located and how multiple versions of the same asset are handled (eg, to target different resolutions). The [asset retargeting task](../../../src/SourceGenerators/Uno.UI.Tasks/Assets/RetargetAssets.cs) copies the image assets located in the shared project to the appropriate location and format for the target platform. ### Formatting string resources -As with images, different platforms have different requirements for location and formatting of localized string resources. The [ResourcesGenerationTask](https://github.com/unoplatform/uno/blob/master/src/SourceGenerators/Uno.UI.Tasks/ResourcesGenerator/ResourcesGenerationTask.cs) reads the strings defined in UWP's `*.resw` files in the shared project, and generates the appropriate platform-specific file. +As with images, different platforms have different requirements for location and formatting of localized string resources. The [ResourcesGenerationTask](../../../src/SourceGenerators/Uno.UI.Tasks/ResourcesGenerator/ResourcesGenerationTask.cs) reads the strings defined in UWP's `*.resw` files in the shared project, and generates the appropriate platform-specific file. diff --git a/doc/articles/uno-development/uno-internals-wasm.md b/doc/articles/contributing/uno-internals-wasm.md similarity index 100% rename from doc/articles/uno-development/uno-internals-wasm.md rename to doc/articles/contributing/uno-internals-wasm.md diff --git a/doc/articles/uno-development/ways-to-contribute.md b/doc/articles/contributing/ways-to-contribute.md similarity index 90% rename from doc/articles/uno-development/ways-to-contribute.md rename to doc/articles/contributing/ways-to-contribute.md index 7c0e33171d77..36b5cd0276e2 100644 --- a/doc/articles/uno-development/ways-to-contribute.md +++ b/doc/articles/contributing/ways-to-contribute.md @@ -21,7 +21,7 @@ Here are questions you can consider before you file a bug to make sure you're no Pre-Submission check: -1. Did you read the [documentation](https://platform.uno/docs/articles/intro.html)? +1. Did you read the [documentation](xref:Uno.Documentation.Intro)? 2. Did you check the latest [pre-release](https://www.nuget.org/packages/Uno.UI/absoluteLatest) of Uno Platform to see if the issue has been fixed? 3. Does the issue exist on the UWP / WinUI project (in which case it is not an Uno Platform issue) @@ -72,7 +72,7 @@ The WinUI framework is pretty big, but many hands make light work. We welcome co ### Diving into the code -The [contributor's guide](contributing-intro.md) has plenty of resources to help you get up and running with Uno's code, including a [guide to building and debugging Uno.UI](debugging-uno-ui.md), and a [guide to Uno's internals](uno-internals-overview.md). +The [contributor's guide](xref:Uno.Contributing.Intro) has plenty of resources to help you get up and running with Uno's code, including a [guide to building and debugging Uno.UI](xref:Uno.Contributing.DebuggingUno), and a [guide to Uno's internals](xref:Uno.Contributing.Overview). ### Finding an issue to work on @@ -84,15 +84,15 @@ In either case, once you're ready, leave a comment on the issue indicating that ### Getting down to work -The [contributor's guide](contributing-intro.md) has the information you need. The most important points are: +The [contributor's guide](xref:Uno.Contributing.Intro) has the information you need. The most important points are: - Work in [your own fork of Uno](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) -- Be sure to use the [Conventional Commits format](git-conventional-commits.md) -- Once you're done, you'll probably need to [add a test](../contributing/guidelines/creating-tests.md) +- Be sure to use the [Conventional Commits format](xref:Uno.Contributing.ConventionalCommits) +- Once you're done, you'll probably need to [add a test](xref:Uno.Contributing.Tests.CreatingTests) ### Creating a PR -Once you're ready to create a PR, check out the [Guidelines for pull requests](../contributing/guidelines/pull-requests.md) in Uno. +Once you're ready to create a PR, check out the [Guidelines for pull requests](xref:Uno.Contributing.PullRequests) in Uno. ### Need help? diff --git a/doc/articles/uno-development/working-with-the-samples-apps.md b/doc/articles/contributing/working-with-the-samples-apps.md similarity index 89% rename from doc/articles/uno-development/working-with-the-samples-apps.md rename to doc/articles/contributing/working-with-the-samples-apps.md index 69fadaedaad4..2bed5ab53935 100644 --- a/doc/articles/uno-development/working-with-the-samples-apps.md +++ b/doc/articles/contributing/working-with-the-samples-apps.md @@ -7,13 +7,13 @@ uid: Uno.Contributing.SamplesApp The SamplesApp in Uno.UI is an Uno application containing a large number of UI and non-UI samples. It serves a few purposes: * Allow for manually testing new features and investigating bugs, -* Provide UI for [automated UI tests](creating-ui-tests.md), +* Provide UI for [automated UI tests](xref:Uno.Contributing.Tests.CreateUITests), * Allow automated comparison of static snapshots between Uno versions, * Document the functionality supported by Uno. This article details how to run SamplesApp and how to add a new sample. -For instructions on working with automated UI tests, [go here](creating-ui-tests.md). +For instructions on working with automated UI tests, [go here](xref:Uno.Contributing.Tests.CreateUITests). ## Running SamplesApp @@ -22,7 +22,7 @@ The SamplesApp from latest master branch for WebAssembly is available online: ht To run the SamplesApp locally: 1. Ensure [your environment is configured](xref:Uno.GetStarted.vs2022) for the platform you want to run on. -2. Open Uno.UI with the [correct target override and solution filter](building-uno-ui.md) for the platform you want to run on. +2. Open Uno.UI with the [correct target override and solution filter](xref:Uno.Contributing.BuildingUno) for the platform you want to run on. 3. Select `SamplesApp.[Platform]` as the startup app. (Eg, `SamplesApp.iOS` if you're running on iOS.) 4. If you're testing on a mobile platform, use a tablet if possible, as the app is optimized for a tablet layout. 5. Run SamplesApp. @@ -37,7 +37,7 @@ By default, SamplesApp starts in debugging mode on localhost, making it inaccess ## Sample organization -Samples are located in the [`UITests.Shared` project](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared). UI-related samples are generally grouped by control, or by functional area for samples that aren't specific to a particular control (eg `VisualStateTests`). Non-UI samples are generally grouped by namespace of the tested feature. +Samples are located in the [`UITests.Shared` project](../../../src/SamplesApp/UITests.Shared). UI-related samples are generally grouped by control, or by functional area for samples that aren't specific to a particular control (eg `VisualStateTests`). Non-UI samples are generally grouped by namespace of the tested feature. Note that there's no 'master list' of samples. Instead, individual samples are tagged with `SampleAttribute` (or `SampleControlInfoAttribute`, for older samples), and the SamplesApp automatically picks up all samples using the attribute. @@ -107,7 +107,7 @@ have changed. ### Troubleshooting the tests -It is possible to enable the chromium head using the configuration parameters in the [app.ts](https://github.com/unoplatform/uno/blob/master/src/SamplesApp/SamplesApp.Wasm.UITests/app.ts) file. +It is possible to enable the chromium head using the configuration parameters in the [app.ts](../../../src/SamplesApp/SamplesApp.Wasm.UITests/app.ts) file. ## Creating performance benchmarks with BenchmarkDotNet diff --git a/doc/articles/controls/WebView.md b/doc/articles/controls/WebView.md index b1af3cb1a5e4..be568043a902 100644 --- a/doc/articles/controls/WebView.md +++ b/doc/articles/controls/WebView.md @@ -1,3 +1,6 @@ +--- +uid: Uno.Controls.WebView +--- # `WebView` (`WebView2`) > Uno Platform supports two `WebView` controls - a legacy `WebView` and a modernized `WebView2` control. For new development, we strongly recommend `WebView2` as it will get further improvements in the future. diff --git a/doc/articles/controls/map-control-support.md b/doc/articles/controls/map-control-support.md index baf0353ee40f..2cc25cfa33a6 100644 --- a/doc/articles/controls/map-control-support.md +++ b/doc/articles/controls/map-control-support.md @@ -83,8 +83,7 @@ To use the map component, you will need an API key for Windows and Android. Here ### Windows -For the detailed procedure for Windows, see [Request a maps authentication key -](https://learn.microsoft.com/windows/uwp/maps-and-location/authentication-key) documentation. +For the detailed procedure for Windows, see [Request a maps authentication key](https://learn.microsoft.com/windows/uwp/maps-and-location/authentication-key) documentation. + Go to + Login to your account or register if you don't have one diff --git a/doc/articles/features/dialogs.md b/doc/articles/features/dialogs.md index 35cd128a3eff..684c2b9fcd0e 100644 --- a/doc/articles/features/dialogs.md +++ b/doc/articles/features/dialogs.md @@ -36,6 +36,7 @@ It is crucial to set the `XamlRoot` property before calling `ShowAsync`. This wa ### Opening a `ContentDialog` from a Model/ViewModel When you want to open a `ContentDialog` from a Model or ViewModel, you can pass the `XamlRoot` from the view to the model or view model by creating a service (e.g., `IXamlRootProvider`) that is initialized at the start of the app with the XamlRoot of the main window. + Here is a more detailed example of how to display a `ContentDialog` with result handling: @@ -68,6 +69,15 @@ private async Task DisplayDeleteFileDialog() } ``` +--- +> [!NOTE] +> This example dialog task must run on the UI thread. If your app uses XAML markup, the best place to execute it is in the code-behind of your XAML page. If your app uses C# markup, execute it directly below the main UI definition of the page class, similar to a regular event handler. + +--- + +> [!IMPORTANT] +> If you attempt to execute this task from within your Model or ViewModel without properly handling the `XamlRoot` (which belongs to the UI layer), you will encounter an exception. This occurs because UI-related code is being executed on a non-UI thread. + ### [MVVM](#tab/mvvm) If you are using the MVVM pattern, you can use the `AsyncRelayCommand` from the Uno Platform to bind the command to the dialog display method. Here is an example of how to bind the command to the dialog display method in the ViewModel: diff --git a/doc/articles/features/shapes-and-brushes.md b/doc/articles/features/shapes-and-brushes.md index ccb2c663b38a..f310c9898319 100644 --- a/doc/articles/features/shapes-and-brushes.md +++ b/doc/articles/features/shapes-and-brushes.md @@ -75,18 +75,18 @@ The brush currently has an important limitation on Android, iOS, and macOS: it c - - - - + @@ -106,7 +106,7 @@ Where you can use which brushes | Usage | SolidColorBrush | ImageBrush | GradientBrush | | -------------------------------------------- | --------------- | -------------------- | --------------- | | `Background` property (many controls/panels) | Yes | Yes (except on Wasm) | Yes | -| `BorderBrush` (`Border`, `Panel`) | Yes | No | Yes (Skia, Android), partial (iOS, WASM) [see below] | +| `BorderBrush` (`Border`, `Panel`) | Yes | No | Yes (Skia, Android), partial (iOS, WASM) [see below](#gradient-border-brush-limitations-on-wasm-and-ios) | | `Foreground` (`TextBlock`) | Yes | No | Yes (Wasm only) | | `Fill` (Shapes) | Yes | Yes (except on Wasm) | Yes | | `Stroke` (Shapes) | Yes | No | Yes (Wasm only) | diff --git a/doc/articles/features/windows-ui-markup-extensions.md b/doc/articles/features/windows-ui-markup-extensions.md index 6fb35ee6017a..7108fff453d2 100644 --- a/doc/articles/features/windows-ui-markup-extensions.md +++ b/doc/articles/features/windows-ui-markup-extensions.md @@ -105,7 +105,7 @@ public class DynamicBindExtension : MarkupExtension The following XAML will display “Page Tag”: ```xml - [!TIP] > For a detailed overview of the Uno Platform project template wizard and all its options, see [this](xref:Uno.GettingStarted.UsingWizard). 1. Click the create button -1. Ensure that the lower left IDE icon shows a check mark and says "Ready" ![A checkmark with a text saying ready](getting-started/wizard/assets/vs2022-ready-statusbar.png). This ensures that the projects have been created, and their dependencies have been restored completely. +1. Ensure that the lower left IDE icon shows a check mark and says "Ready" ![A checkmark with a text saying ready](wizard/assets/vs2022-ready-statusbar.png). This ensures that the projects have been created, and their dependencies have been restored completely. 1. A Windows Firewall window may appear. If you do not intend to do Linux development with WSL, check "Private networks" only. Otherwise, check "Public networks" and "Private networks". -1. A banner at the top of the editor may ask to reload projects, click **Reload projects**: +1. A banner at the top of the editor may ask to reload projects, click **Reload projects**: ![Visual Studio - A banner indicating to reload projects](Assets/quick-start/vs2022-project-reload.png) 1. > [!IMPORTANT] @@ -72,7 +72,7 @@ To run the **WebAssembly** (Wasm) head: - In the debugger toolbar, click the down arrow to select **MyApp (WebAssembly)** - ![Visual Studio - Select the Wasm profile](getting-started/wizard/assets/wasm-debugger-dropdown.png) + ![Visual Studio - Select the Wasm profile](wizard/assets/wasm-debugger-dropdown.png) - Press the `MyApp (WebAssembly)` button to deploy the app - To run/debug your WebAssembly app on a mobile device, you can utilize the Dev Tunnels feature of Visual Studio 2022 (see [Microsoft Learn documentation](https://learn.microsoft.com/aspnet/core/test/dev-tunnels) to get started) @@ -90,7 +90,7 @@ To run the **Windows** (WinAppSDK) head: - In the debugger toolbar, click the down arrow to select **MyApp (WinAppSDK Packaged)** or **MyApp (WinAppSDK Unpackaged)** - ![Visual Studio - Select the WinappSDK profile](getting-started/wizard/assets/winappsdk-debugger-dropdown.png) + ![Visual Studio - Select the WinappSDK profile](wizard/assets/winappsdk-debugger-dropdown.png) - Press the `MyApp (WinAppSDK Packaged)` or `MyApp (WinAppSDK Unpackaged)` button to deploy the app - If you have not enabled Developer Mode, the Settings app should open to the appropriate page. Turn on Developer Mode and accept the disclaimer. @@ -145,4 +145,4 @@ Learn more about: - [Uno Platform App solution structure](xref:Uno.Development.AppStructure) - [Troubleshooting](xref:Uno.UI.CommonIssues) - [How-tos and Tutorials](xref:Uno.Tutorials.Intro) See real-world examples with working code. -- [List of views implemented in Uno](implemented-views.md) for the set of available controls and their properties. +- [List of views implemented in Uno](..\implemented-views.md) for the set of available controls and their properties. diff --git a/doc/articles/create-an-app-vscode.md b/doc/articles/getting-started/create-an-app-vscode.md similarity index 100% rename from doc/articles/create-an-app-vscode.md rename to doc/articles/getting-started/create-an-app-vscode.md diff --git a/doc/articles/get-started-explore.md b/doc/articles/getting-started/get-started-explore.md similarity index 100% rename from doc/articles/get-started-explore.md rename to doc/articles/getting-started/get-started-explore.md diff --git a/doc/articles/get-started-licensing.md b/doc/articles/getting-started/get-started-licensing.md similarity index 100% rename from doc/articles/get-started-licensing.md rename to doc/articles/getting-started/get-started-licensing.md diff --git a/doc/articles/get-started-next-steps.md b/doc/articles/getting-started/get-started-next-steps.md similarity index 100% rename from doc/articles/get-started-next-steps.md rename to doc/articles/getting-started/get-started-next-steps.md diff --git a/doc/articles/get-started-rider.md b/doc/articles/getting-started/get-started-rider.md similarity index 100% rename from doc/articles/get-started-rider.md rename to doc/articles/getting-started/get-started-rider.md diff --git a/doc/articles/get-started-vs-2022.md b/doc/articles/getting-started/get-started-vs-2022.md similarity index 87% rename from doc/articles/get-started-vs-2022.md rename to doc/articles/getting-started/get-started-vs-2022.md index 8a2eca3d06ff..e599da257e11 100644 --- a/doc/articles/get-started-vs-2022.md +++ b/doc/articles/getting-started/get-started-vs-2022.md @@ -6,7 +6,7 @@ uid: Uno.GetStarted.vs2022 This getting started will guide you through setting up your environment to create Uno Platform applications using C# and .NET with Visual Studio 2022. > [!TIP] -> If you want to use another environment or IDE, see our [general getting started](get-started.md). +> If you want to use another environment or IDE, see our [general getting started](xref:Uno.GetStarted). ## Install Visual Studio with Workloads @@ -27,21 +27,21 @@ To create Uno Platform applications you will need [**Visual Studio 2022 17.8 or > [!NOTE] > If you intend to do Linux development with WSL, make sure to select **.NET Debugging with WSL** in the **Individual components** section. > [!IMPORTANT] -> Uno Platform 5.0 and later [does not support Xamarin projects anymore](xref:Uno.Development.MigratingToUno5). To build Xamarin-based projects in Visual Studio 2022, in Visual Studio's installer `Individual components` tab, search for Xamarin and select `Xamarin` and `Xamarin Remoted Simulator`. See [this section on migrating Xamarin projects](migrating-from-xamarin-to-net6.md) to .NET 6. +> Uno Platform 5.0 and later [does not support Xamarin projects anymore](xref:Uno.Development.MigratingToUno5). To build Xamarin-based projects in Visual Studio 2022, in Visual Studio's installer `Individual components` tab, search for Xamarin and select `Xamarin` and `Xamarin Remoted Simulator`. See [this section on migrating Xamarin projects](xref:Uno.Development.MigratingFromXamarinToNet6) to .NET 6. ## Check your environment -[!include[use-uno-check](includes/use-uno-check-inline-windows-noheader.md)] +[!include[use-uno-check](xref:Uno.uno-check-inline.Windows)] ## Install the Uno Platform Extension -1. Launch Visual Studio 2022, then click `Continue without code`. Click `Extensions` -> `Manage Extensions` from the Menu Bar. +1. Launch Visual Studio 2022, then click `Continue without code`. Click `Extensions` -> `Manage Extensions` from the Menu Bar. - ![Visual Studio - "Extensions" drop-down selecting "Manage Extensions"](Assets/tutorial01/manage-extensions.png) + ![Visual Studio - "Extensions" drop-down selecting "Manage Extensions"](Assets/tutorial01/manage-extensions.png) -2. In the Extension Manager expand the **Online** node and search for `Uno`, install the `Uno Platform` extension or download it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=unoplatform.uno-platform-addin-2022), then restart Visual Studio. +2. In the Extension Manager expand the **Online** node and search for `Uno`, install the `Uno Platform` extension or download it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=unoplatform.uno-platform-addin-2022), then restart Visual Studio. - ![Extension Manager - Uno Platform extension](Assets/tutorial01/uno-extensions.PNG) + ![Extension Manager - Uno Platform extension](Assets/tutorial01/uno-extensions.PNG) ## Additional Setup for Windows Subsystem for Linux (WSL) @@ -59,7 +59,7 @@ To setup your environment for WSL: ### WSL -[!include[linux-setup](includes/additional-linux-setup-inline.md)] +[!include[linux-setup](../includes/additional-linux-setup-inline.md)] --- diff --git a/doc/articles/get-started-vscode-devkit.md b/doc/articles/getting-started/get-started-vscode-devkit.md similarity index 100% rename from doc/articles/get-started-vscode-devkit.md rename to doc/articles/getting-started/get-started-vscode-devkit.md diff --git a/doc/articles/get-started-vscode-omnisharp.md b/doc/articles/getting-started/get-started-vscode-omnisharp.md similarity index 100% rename from doc/articles/get-started-vscode-omnisharp.md rename to doc/articles/getting-started/get-started-vscode-omnisharp.md diff --git a/doc/articles/get-started-vscode.md b/doc/articles/getting-started/get-started-vscode.md similarity index 100% rename from doc/articles/get-started-vscode.md rename to doc/articles/getting-started/get-started-vscode.md diff --git a/doc/articles/get-started.md b/doc/articles/getting-started/get-started.md similarity index 92% rename from doc/articles/get-started.md rename to doc/articles/getting-started/get-started.md index 50b4b9f5596e..e376d62d4ea6 100644 --- a/doc/articles/get-started.md +++ b/doc/articles/getting-started/get-started.md @@ -1,13 +1,17 @@ --- uid: Uno.GetStarted --- + ## Quick Start -1. Install and run Uno.Check to set up all the required pre-requisites -2. Download the Uno Platform extension for your IDE: +1. Install the [.NET SDK](https://dotnet.microsoft.com/en-us/download/dotnet/latest) to get `dotnet` available in your commandline. +2. Install and run [Uno.Check](xref:UnoCheck.UsingUnoCheck) to set up all the required pre-requisites. + a. Detailed [Configuration Options](xref:UnoCheck.Configuration) for Uno-Check + b. If you run into issues with it, see [Troubleshooting Uno-Check](xref:UnoCheck.Troubleshooting) +3. Download the Uno Platform extension for your IDE: - +
@@ -65,12 +69,6 @@ If you're developing on Windows, we recommend you use [**Visual Studio 2022**](x If you already use and love **JetBrains Rider** or **Visual Studio Code**, you can also use them to develop Uno Platform applications. Check the support matrix below to see which target platforms they support. -**Choose the IDE you want to use:** - -- [Visual Studio 2022](xref:Uno.GetStarted.vs2022) -- [VS Code, Codespaces and GitPod](xref:Uno.GetStarted.vscode) -- [Rider](xref:Uno.GetStarted.Rider) - To help you choose the appropriate IDE, the following table shows the compatibility of different development environments with various target platforms: | | [**Visual Studio**](xref:Uno.GetStarted.vs2022) | [**VS Code**](xref:Uno.GetStarted.vscode) | [**Codespaces / Gitpod**](xref:Uno.GetStarted.vscode) | [**JetBrains Rider**](xref:Uno.GetStarted.Rider) | @@ -86,14 +84,15 @@ To help you choose the appropriate IDE, the following table shows the compatibil - †† You will need to be connected to a Mac using [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) - ††† [WebAssembly debugging](https://youtrack.jetbrains.com/issue/RIDER-103346/Uno-Platform-for-WebAssembly-debugger-support) is not yet supported -# [**macOS**](#tab/macos) +**Choose the IDE you want to use:** -You can use **Visual Studio Code** or **JetBrains Rider**, to build Uno Platform applications on macOS. See the support matrix below for supported target platforms. +- [Visual Studio 2022](xref:Uno.GetStarted.vs2022) +- [VS Code, Codespaces and GitPod](xref:Uno.GetStarted.vscode) +- [Rider](xref:Uno.GetStarted.Rider) -**Choose the IDE you want to use:** +# [**macOS**](#tab/macos) -- [Get started with VS Code, Codespaces and GitPod](xref:Uno.GetStarted.vscode) -- [Get started with Rider](xref:Uno.GetStarted.Rider) +You can use **Visual Studio Code** or **JetBrains Rider**, to build Uno Platform applications on macOS. See the support matrix below for supported target platforms. To help you choose the appropriate IDE, the following table shows the compatibility of different development environments with various target platforms: @@ -108,15 +107,15 @@ To help you choose the appropriate IDE, the following table shows the compatibil The latest macOS release and Xcode version are required to develop with Uno Platform for iOS and Mac Catalyst targets. If you have older Mac hardware that does not support the latest release of macOS, see the section for [Developing on older Mac hardware](xref:Uno.UI.CommonIssues.IosCatalyst#developing-on-older-mac-hardware). -# [**Linux**](#tab/linux) - - You can use either **JetBrains Rider** or **Visual Studio Code** to build Uno Platform applications on Linux. See the support matrix below for supported target platforms. - **Choose the IDE you want to use:** -- [Get started with Visual Studio Code, Codespaces and GitPod](xref:Uno.GetStarted.vscode) +- [Get started with VS Code, Codespaces and GitPod](xref:Uno.GetStarted.vscode) - [Get started with Rider](xref:Uno.GetStarted.Rider) +# [**Linux**](#tab/linux) + + You can use either **JetBrains Rider** or **Visual Studio Code** to build Uno Platform applications on Linux. See the support matrix below for supported target platforms. + To help you choose the appropriate IDE, the following table shows the compatibility of different development environments with various target platforms: | | [**VS Code**](xref:Uno.GetStarted.vscode) | [**Codespaces / Gitpod**](xref:Uno.GetStarted.vscode) | [**JetBrains Rider**](xref:Uno.GetStarted.Rider) | @@ -132,16 +131,14 @@ To help you choose the appropriate IDE, the following table shows the compatibil - † [WebAssembly debugging](https://youtrack.jetbrains.com/issue/RIDER-103346/Uno-Platform-for-WebAssembly-debugger-support) is not yet supported ---- - -## Questions +**Choose the IDE you want to use:** -For questions about Uno Platform, refer to the [general FAQ](xref:Uno.Development.FAQ) or see the [troubleshooting section](xref:Uno.UI.CommonIssues) for common issues and their solutions. +- [Get started with Visual Studio Code, Codespaces and GitPod](xref:Uno.GetStarted.vscode) +- [Get started with Rider](xref:Uno.GetStarted.Rider) -## Next Steps +--- -Choose the IDE to Learn more about: +## See Also -- [Visual Studio 2022](xref:Uno.GetStarted.vs2022) -- [VS Code, Codespaces and GitPod](xref:Uno.GetStarted.vscode) -- [Rider](xref:Uno.GetStarted.Rider) +- Questions about Uno Platform: [FAQ](xref:Uno.Development.FAQ) +- Common issues and their solutions: [Troubleshooting](xref:Uno.UI.CommonIssues). diff --git a/doc/articles/get-started-wizard.md b/doc/articles/getting-started/wizard/get-started-wizard.md similarity index 75% rename from doc/articles/get-started-wizard.md rename to doc/articles/getting-started/wizard/get-started-wizard.md index 12be5e8d5874..83724744375b 100644 --- a/doc/articles/get-started-wizard.md +++ b/doc/articles/getting-started/wizard/get-started-wizard.md @@ -2,7 +2,7 @@ uid: Uno.GetStarted.Wizard --- - + # Done! Important next steps: Create a simple cross-platform Counter application. @@ -16,7 +16,7 @@ Choose one of the 4 variants of the Counter tutorial, combining markup language
- +
#### XAML + MVUX @@ -28,7 +28,7 @@ Use XAML for layout and MVUX for state management
- +
#### XAML + MVVM @@ -40,7 +40,7 @@ Use XAML for layout and MVVM for state management
- +
#### C# Markup + MVUX @@ -52,7 +52,7 @@ Use C# Markup for layout and MVUX for state management
- +
#### C# Markup + MVVM @@ -68,7 +68,7 @@ Use C# Markup for layout and MVVM for state management
- +
#### Hot Design @@ -82,4 +82,4 @@ Use a visual designer to design and develop the app
-[!include[getting-help](includes/getting-help.md)] +[!include[getting-help](xref:Uno.Development.GettingHelp)] diff --git a/doc/articles/guides/how-to-create-control-libraries.md b/doc/articles/guides/how-to-create-control-libraries.md index f1c4e8358f95..26fda52d3f3f 100644 --- a/doc/articles/guides/how-to-create-control-libraries.md +++ b/doc/articles/guides/how-to-create-control-libraries.md @@ -108,7 +108,7 @@ In a Control Class Library, [conditional XAML](xref:Uno.Development.PlatformSpec ## Library assets -WinUI 3 and Uno Platform (4.6 and later) Libraries support the inclusion of content assets to be used with [`StorageFile.GetFileFromApplicationUriAsync`](../features/file-management.md#support-for-storagefilegetfilefromapplicationuriasync), as well as with the `ms-appx:///[libraryname]/[assetname_file_name]` format. +WinUI 3 and Uno Platform (4.6 and later) Libraries support the inclusion of content assets to be used with [`StorageFile.GetFileFromApplicationUriAsync`](xref:Uno.Features.FileManagement#support-for-storagefilegetfilefromapplicationuriasync), as well as with the `ms-appx:///[libraryname]/[assetname_file_name]` format. > [!IMPORTANT] > When using library assets with non-WinAppSDK targets, the library name should also be lower cased. @@ -129,4 +129,4 @@ In both cases, for the build system to include the assets files, the following p ``` > [!IMPORTANT] -> WinAppSDK [does not support assets](https://github.com/microsoft/microsoft-ui-xaml/issues/6429) if the application is using the MSIX package mode. To use the unpackaged mode, [see this article](../features/winapp-sdk-specifics.md#unpackaged-application-support). +> WinAppSDK [does not support assets](https://github.com/microsoft/microsoft-ui-xaml/issues/6429) if the application is using the MSIX package mode. To use the unpackaged mode, [see this article](xref:Uno.Features.WinAppSDK#un-packaged-application-support). diff --git a/doc/articles/includes/clean-architecture-principles-inline.md b/doc/articles/includes/clean-architecture-principles-inline.md new file mode 100644 index 000000000000..458a1407841f --- /dev/null +++ b/doc/articles/includes/clean-architecture-principles-inline.md @@ -0,0 +1,5 @@ +--- +uid: Uno.Clean-Architecture-Inline +--- + +[Clean Architecture principles](https://devblogs.microsoft.com/ise/next-level-clean-architecture-boilerplate) diff --git a/doc/articles/includes/use-uno-check-inline-windows-noheader.md b/doc/articles/includes/use-uno-check-inline-windows-noheader.md index 85c10aa81628..e8f43ec9f746 100644 --- a/doc/articles/includes/use-uno-check-inline-windows-noheader.md +++ b/doc/articles/includes/use-uno-check-inline-windows-noheader.md @@ -1,3 +1,6 @@ +--- +uid: Uno.uno-check-inline.Windows +--- 1. Open a command-line prompt, Windows Terminal if you have it installed, or else Command Prompt or Windows Powershell from the Start menu. 1. Setup uno.check by: diff --git a/doc/articles/studio/Hot Design/Assets/logo.svg b/doc/articles/studio/Hot Design/Assets/logo.svg new file mode 100644 index 000000000000..8ffc41ae3a5d --- /dev/null +++ b/doc/articles/studio/Hot Design/Assets/logo.svg @@ -0,0 +1,137 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/articles/toc.yml b/doc/articles/toc.yml index 565104fdc844..89c4789e09e6 100644 --- a/doc/articles/toc.yml +++ b/doc/articles/toc.yml @@ -10,7 +10,7 @@ href: xref:Uno.GetStarted.vscode - name: Rider href: xref:Uno.GetStarted.Rider - + - name: Create an App topicHref: xref:Uno.GettingStarted.CreateAnApp.VS2022 items: @@ -67,6 +67,8 @@ href: xref:Uno.Development.Troubleshooting - name: Build error codes href: xref:Build.Solution.error-codes + - name: Troubleshooting source generation + href: xref:Uno.Development.Troubleshooting.SourceGeneration - name: Samples & Tutorials topicHref: xref:Uno.SamplesTutorials.Overview @@ -155,20 +157,20 @@ - name: Architecture items: - name: Supported Platforms - href: getting-started/requirements.md + href: xref:Uno.GettingStarted.Requirements items: - name: .NET Versions href: net-version-support.md - name: Working with Skia Desktop href: xref:Uno.Skia.Desktop - name: Working with the Linux Framebuffer - href: features/using-linux-framebuffer.md + href: xref:Uno.Skia.Linux.Framebuffer - name: Philosophy - href: concepts/overview/philosophy-of-uno.md + href: xref:Uno.Overview.Philosophy - name: How Uno Works - href: how-uno-works.md + href: xref:Uno.Development.HowItWorks - name: Best practices - href: best-practices-uno.md + href: xref:Uno.Development.BestPractices - name: Authoring items: @@ -181,9 +183,9 @@ - name: Creating Custom Controls href: guides/creating-custom-controls.md - name: Control Libraries - href: guides/how-to-create-control-libraries.md + href: xref:Guide.HowTo.Create-Control-Library - name: Adding New Platforms - href: guides/how-to-add-platforms-existing-project.md + href: xref:Uno.Guides.AddAdditionalPlatforms - name: Getting Started With Tests href: xref:Uno.Authoring.Tests - name: Logging @@ -197,14 +199,14 @@ - name: Legacy Topics items: - name: Working with Skia+GTK - href: features/using-skia-gtk.md + href: xref:Uno.Skia.Gtk - name: Debugging items: - name: How to create a repro sample href: uno-howto-create-a-repro.md - name: 'Debugging C# on WASM' - href: debugging-wasm.md + href: xref:Uno.Development.DebuggingWasm - name: VS Code Advanced Mobile Debugging href: xref:uno.vscode.mobile.advanced.debugging - name: Generic Unhandled Exceptions handler @@ -215,10 +217,10 @@ - name: Embedding items: - name: Uno Platform in WPF - href: guides/uno-islands.md + href: xref:Uno.Tutorials.UnoIslands - name: Native Views with Mobile - href: native-views.md - - name: Native Views with Skia + href: xref:Uno.Development.NativeViews + - name: Native Views with Skia href: xref:Uno.Skia.Embedding.Native - name: Upgrading @@ -262,7 +264,7 @@ - name: General guidance href: migrating-guidance.md - name: Silverlight - topicHref: guides/silverlight-migration/silverlight-migration-landing.md + topicHref: xref:Uno.SilverlightMigration.Landing href: guides/silverlight-migration/toc.yml - name: Publishing @@ -311,110 +313,129 @@ - name: IL Linker for WebAssembly href: xref:uno.articles.features.illinker - name: Working with String Resource Trimming - href: features/upri-trimming.md + href: xref:Uno.Features.StringResourceTrimming - name: Working with XAML Trimming - href: features/resources-trimming.md + href: xref:Uno.Features.ResourcesTrimming - name: Error Monitoring & Crash Reporting with Raygun href: xref:Monitoring.Raygun - name: Contributing items: - name: Overview - href: uno-development/contributing-intro.md + href: xref:Uno.Contributing.Intro - name: Code of Conduct - href: https://github.com/unoplatform/uno/blob/master/CODE_OF_CONDUCT.md + href: ../../CODE_OF_CONDUCT.md - name: Ways to contribute - href: uno-development/ways-to-contribute.md + href: xref:Uno.Contributing.WaysToContribute - name: How Uno works + href: xref:Uno.Contributing.Internals.Overview items: - name: Overview - href: uno-development/uno-internals-overview.md + href: xref:Uno.Contributing.Overview - name: Android - href: uno-development/uno-internals-android.md + href: xref:Uno.Contributing.Android - name: Layouting in Android - href: uno-development/Uno-UI-Layouting-Android.md + href: xref:Uno.Contributing.Layouting.Android - name: iOS - href: uno-development/uno-internals-ios.md + href: Uno.Contributing.iOS - name: Layouting in iOS - href: uno-development/Uno-UI-Layouting-iOS.md + href: xref:Uno.Contributing.Layouting.iOS - name: WASM - href: uno-development/uno-internals-wasm.md + href: xref:Uno.Contributing.Wasm - name: macOS - href: uno-development/uno-internals-macos.md + href: xref:Uno.Contributing.macOS - name: DependencyProperty backing generator - href: uno-development/Internal-DependencyProperty-Generator.md + href: xref:Uno.Contributing.DependencyPropertyGenerator - name: x:Bind in Uno Platform - href: uno-development/Uno-UI-xBind-architecture.md + href: xref:Uno.Contributing.xBind - name: ListViewBase - href: uno-development/listviewbase-internals.md + href: xref:Uno.Contributing.ListViewBase - name: ThemeResource - href: uno-development/themeresource-internals.md + href: xref:Uno.Contributing.ThemeResource - name: InteractionTracker internals - href: uno-development/interaction-tracker-internals.md - - name: Building Uno.UI - href: uno-development/building-uno-ui.md - - name: Debugging Uno.UI - href: uno-development/debugging-uno-ui.md - - name: Building Uno.UI for macOS using Visual Studio for Mac - href: uno-development/building-uno-macos.md - - name: Using Codespaces - href: features/working-with-codespaces.md - - name: Using Gitpod - href: features/working-with-gitpod.md - - name: Inspecting the visual tree - href: uno-development/debugging-inspect-visual-tree.md - - name: Guidelines for code style - href: contributing/guidelines/code-style.md - - name: Using the SamplesApp - href: uno-development/working-with-the-samples-apps.md + href: xref:Uno.Contributing.InteractionTracker + - name: Guidelines for Contributing Documentation + items: + - name: Adding documentation + href: xref:Uno.Contributing.Docs + - name: DocFX + href: xref:Uno.Contributing.DocFx + - name: Toc Checker + href: xref:Uno.Contributing.check-toc.Overview + items: + - name: Overview + href: xref:Uno.Contributing.check-toc.Overview + - name: How-To Use the TOC Checker + href: xref:Uno.Contributing.check-toc.Guide + - name: Utility Functions for the TOC Checker + href: xref:Uno.Contributing.check-toc.Utilities + - name: Contributing to Uno.UI + topicHref: xref:Uno.Contributing.BuildingUno + items: + - name: Building Uno.UI + href: xref:Uno.Contributing.BuildingUno + - name: Debugging Uno.UI + href: xref:Uno.Contributing.DebuggingUno + - name: Building Uno.UI for macOS using Visual Studio for Mac + href: xref:Uno.Contributing.BuildingUno.macOS + - name: Guidelines for code style + href: xref:Uno.Contributing.CodeStyle + - name: Git + href: xref:Uno.Contributing.Source-Control + items: + - name: Source Control Overview + href: xref:Uno.Contributing.Source-Control + - name: Using Codespaces + href: xref:Uno.Features.Codespaces + - name: Using Gitpod + href: xref:Uno.Features.Gitpod - name: Guidelines for creating tests + href: xref:Uno.Contributing.Tests.CreatingTests items: - name: Overview - href: contributing/guidelines/creating-tests.md + href: xref:Uno.Contributing.Tests.CreatingTests - name: Mocked unit tests (Uno.UI.Tests) - href: uno-development/creating-mocked-tests.md + href: xref:Uno.Contributing.Tests.Creating-mocked-tests.md - name: Platform-runtime unit tests (Uno.UI.RuntimeTests) - href: uno-development/creating-runtime-tests.md + href: xref:Uno.Contributing.Tests.CreateRuntimeTests - name: UI tests with Uno.UITest - href: uno-development/creating-ui-tests.md - - name: Debugging Solution Templates - href: uno-development/debugging-templates.md - - name: Conventional Commits format - href: uno-development/git-conventional-commits.md - - name: Guidelines for pull-requests - href: contributing/guidelines/pull-requests.md - - name: Guidelines for breaking changes - href: contributing/guidelines/breaking-changes.md - - name: Guidelines for updating dependencies - href: contributing/guidelines/updating-dependencies.md - - name: Guidelines for issue triage - href: contributing/guidelines/issue-triage.md + href: xref:Uno.Contributing.Tests.CreateUITests + - name: Testing PowerShell Scripts with Pester + href: xref:Uno.Contributing.Tests.PowerShell-Pester-Tests + - name: Using the SamplesApp + href: xref:Uno.Contributing.SamplesApp + - name: Inspecting the visual tree + href: xref:Uno.Contributing.InspectVisualTree - name: Guidelines for implementing a new WinUI/WinRT feature - href: contributing/guidelines/implementing-a-new-winui-winrt-feature.md - - name: Adding documentation - href: uno-development/doc-on-docs.md - - name: DocFX - href: uno-development/docfx.md - - name: Uno.UI release procedure - href: uno-development/release-procedure.md - - name: Build Artifacts - href: contributing/build-artifacts.md + href: xref:Uno.Contributing.ImplementWinUIWinRT-API - name: Advanced topics items: - name: Adding functionality with API extensions - href: uno-development/api-extensions.md + href: xref:Uno.Contributing.ApiExtensions - name: The WeakEventHelper class - href: uno-development/Internal-WeakEventHelper.md + href: xref:Uno.Contributing.WeakEventHelper - name: Debugging Uno.UI Java code with Android studio - href: uno-development/Uno-UI-Debugging-Android-Studio.md + href: xref:Uno.Contributing.AndroidStudio - name: Troubleshooting Memory Issues - href: uno-development/troubleshooting-memory-issues.md + href: xref:Uno.Contributing.MemoryIssues - name: Troubleshooting Source Generation - href: uno-development/troubleshooting-source-generation.md + href: xref:Uno.Contributing.SourceGeneration - name: The XAML Trimming phase - href: uno-development/Uno-UI-XAML-ResourceTrimming.md + href: xref:Uno.Contributing.XamlResourceTrimming - name: Hot Reload internals href: xref:Uno.Contributing.Internals.HotReload + - name: Guidelines for updating dependencies + href: xref:Uno.Contributing.UpdatingDependencies + - name: Breaking changes + href: xref:Uno.Contributing.BreakingChanges + - name: Release Procedure + href: xref:Uno.Contributing.ReleaseProcedure + - name: Build Artifacts + href: xref:Uno.Contributing.BuildArtifacts + - name: Guidelines for issue triage + href: xref:Uno.Contributing.IssueTriage + - name: Debugging Solution Templates + href: xref:Uno.Contributing.DebuggingTemplates - name: Why use Uno Platform? href: xref:Uno.Overview.WhyUno - name: FAQ @@ -459,17 +480,17 @@ - name: Uno and WinUI 3 href: uwp-vs-winui3.md - name: WinAppSDK Specifics - href: features/winapp-sdk-specifics.md + href: xref:Uno.Features.WinAppSDK - name: WinUI links items: - name: Overview - href: winui-doc-links.md + href: xref:Uno.Development.WinUIDoc - name: Tutorials - href: winui-doc-links-tutorials.md + href: Uno.Development.WinUITutorialsDoc - name: Development - href: winui-doc-links-development.md + href: xref:Uno.Development.WinUIDevelopmentDoc - name: Design - href: winui-doc-links-design.md + href: xref:Uno.Development.WinUIDesignDoc - name: UI items: @@ -485,212 +506,212 @@ - name: Activities in Android href: android-activities.md - name: ComboBox - href: controls/ComboBox.md + href: xref:Uno.Controls.ComboBox - name: CommandBar - href: controls/CommandBar.md + href: xref:Uno.Controls.CommandBar - name: DatePicker - href: controls/DatePicker.md + href: xref:Uno.Controls.DatePicker - name: ElevatedView - href: features/ElevatedView.md + href: xref:Uno.Features.ElevatedView - name: Fluent icon font - href: uno-fluent-assets.md + href: xref:Uno.Development.FluentAssets - name: Flyout - href: controls/Flyout.md + href: xref:Uno.Controls.Flyout - name: Frame - href: controls/Frame.md + href: xref:Uno.Controls.Frame - name: GLCanvasElement href: xref:Uno.Controls.GLCanvasElement - name: Image href: xref:Uno.Features.Image - name: ListView and GridView - href: controls/ListViewBase.md + href: xref:Uno.Controls.ListViewBase - name: Lottie animations - href: features/Lottie.md + href: xref:Uno.Features.Lottie - name: MapControl - href: controls/map-control-support.md + href: xref:Uno.Controls.MapControl - name: MediaPlayerElement - href: controls/MediaPlayerElement.md + href: xref:Uno.Controls.MediaPlayerElement - name: MenuFlyout - href: controls/MenuFlyout.md + href: xref:Uno.Controls.MenuFlyout - name: NavigationView - href: controls/NavigationView.md + href: xref:Uno.Controls.NavigationView - name: Native control styles - href: native-styles.md + href: xref:Uno.Development.NativeViews - name: Other features href: xref:Uno.Development.AdditionalFeatures - name: Pivot - href: controls/Pivot.md + href: xref:Uno.Controls.Pivot - name: Popup - href: controls/Popup.md + href: xref:Uno.Controls.Popup - name: ProgressRing - href: features/progressring.md + href: xref:Uno.Features.ProgressRing - name: RefreshContainer (Pull to Refresh) - href: controls/RefreshContainer.md + href: xref:Uno.Controls.RefreshContainer - name: ScrollViewer - href: controls/ScrollViewer.md + href: xref:Uno.Controls.ScrollViewer - name: SKCanvasElement href: xref:Uno.Controls.SKCanvasElement - name: TextBox - href: controls/TextBox.md + href: xref:Uno.Controls.TextBox - name: TimePicker - href: controls/TimePicker.md + href: xref:Uno.Controls.TimePicker - name: ToggleSwitch - href: controls/ToggleSwitch.md + href: xref:Uno.Controls.ToggleSwitch - name: URI Protocol activation - href: features/protocol-activation.md + href: xref:Uno.Features.ProtocolActivation - name: Using pointer cursors - href: features/cursors.md + href: xref:Uno.Features.Cursors - name: Using SVG images - href: features/svg.md + href: xref:Uno.Features.SVG - name: VisibleBoundsPadding href: xref:Uno.Features.VisibleBoundsPadding - name: WebView (WebView2) - href: controls/WebView.md + href: xref:Uno.Controls.WebView - name: Features items: - name: Accessibility - href: features/working-with-accessibility.md + href: xref:Uno.Features.Accessibility - name: Animations - href: features/working-with-animations.md + href: xref:Uno.Features.Animations - name: Assets and image display - href: features/working-with-assets.md + href: xref:Uno.Features.Assets - name: Build telemetry - href: uno-toolchain-telemetry.md + href: xref:Uno.Development.ToolchainTelemetry - name: Composition API - href: composition.md + href: xref:Uno.Development.Composition - name: Dialogs - href: features/dialogs.md + href: xref:Uno.Features.Dialogs - name: Fluent styles - href: features/fluent-styles.md + href: xref:Uno.Features.FluentStyles - name: Focus management - href: features/focus-management.md + href: xref:Uno.Features.FocusManagement - name: Fonts - href: features/custom-fonts.md + href: xref:Uno.Features.CustomFonts - name: Markup Extensions - href: features/windows-ui-markup-extensions.md + href: xref:Uno.Features.WinUIMarkupExtension - name: Native frame navigation - href: features/native-frame-nav.md + href: xref:Uno.Features.NativeFrameNav - name: Orientation - href: features/orientation.md + href: xref:Uno.Features.Orientation - name: Routed Events - href: features/routed-events.md + href: xref:Uno.Features.RoutedEvents - name: Shapes & Brushes - href: features/shapes-and-brushes.md + href: xref:Uno.Features.ShapesAndBrushes - name: String resources and localization - href: features/working-with-strings.md + href: xref:Uno.Features.Localization - name: Succinct syntax - href: features/windows-ui-succinct-syntax.md + href: xref:Uno.Features.WinUISuccinctSyntax - name: Themes - href: features/working-with-themes.md + href: xref:Uno.Features.Themes - name: User inputs - Keyboard, Pointers, Gestures, Manipulations, Drag and drop - href: features/pointers-keyboard-and-other-user-inputs.md + href: xref:Uno.Features.UserInputs - name: Using Fluent styles in legacy apps - href: features/using-winui2.md + href: xref:Uno.Features.WinUI2 - name: Windowing - href: features/windows-ui-xaml-window.md + href: xref:Uno.Features.WinUIWindow - name: x:Bind - href: features/windows-ui-xbind.md + href: xref:Uno.Features.WinUIxBind - name: 3rd-party libraries - href: supported-libraries.md + href: xref:Uno.Development.SupportedLibraries - name: Non-UI items: - name: Accelerometer - href: features/accelerometer.md + href: xref:Uno.Features.Accelerometer - name: Android TV - href: features/android-tv.md + href: xref:Uno.Features.AndroidTv - name: App Actions - href: features/windows-ui-startscreen.md + href: xref:Uno.Features.WinUIStartScreen - name: App Close Handler - href: features/app-close-handler.md + href: xref:Uno.Features.AppCloseHandler - name: App Suspension - href: features/windows-ui-xaml-application.md + href: xref:Uno.Features.WinUIApplication - name: Application Data and Settings - href: features/applicationdata.md + href: xref:Uno.Features.ApplicationData - name: Badge Notifications - href: features/windows-ui-notifications.md + href: xref:Uno.Features.WinUINotifications - name: Barometer - href: features/barometer.md + href: xref:Uno.Features.Barometer - name: Battery Information - href: features/windows-system-power.md + href: xref:Uno.Features.WSPower - name: Bluetooth - href: features/bluetoothdevice.md + href: xref:Uno.Features.BluetoothDevice - name: Capture (Camera) - href: features/windows-media-capture.md + href: xref:Uno.Features.Capture - name: Clipboard - href: features/clipboard.md + href: xref:Uno.Features.Clipboard - name: Compass - href: features/compass.md + href: xref:Uno.Features.Compass - name: Contacts - href: features/windows-applicationmodel-contacts.md + href: xref:Uno.Features.WAMContacts - name: Credential Storage - href: features/PasswordVault.md + href: xref:Uno.Features.PasswordVault - name: Device Enumeration - href: features/windows-devices-enumeration.md + href: xref:Uno.Features.WDEnumeration - name: Device Information - href: features/windows-system-profile.md + href: xref:Uno.Features.WSProfile - name: E-mail - href: features/windows-applicationmodel-email.md + href: xref:Uno.Features.WAMEmail - name: File and Folder Pickers - href: features/windows-storage-pickers.md + href: xref:Uno.Features.WSPickers - name: File Management - href: features/file-management.md + href: xref:Uno.Features.FileManagement - name: Flashlight - href: features/flashlight.md + href: xref:Uno.Features.Flashlight - name: Gamepad - href: features/gamepad.md + href: xref:Uno.Features.Gamepad - name: Geolocation (GPS) - href: features/windows-devices-geolocation.md + href: xref:Uno.Features.WDGeolocation - name: Gyrometer - href: features/gyrometer.md + href: xref:Uno.Features.Gyrometer - name: Haptics - href: features/windows-devices-haptics.md + href: xref:Uno.Features.WDHaptics - name: Hardware back button - href: features/hardware-back-button.md + href: xref:Uno.Features.HardwareBackButton - name: Keeping Screen On - href: features/windows-system-display.md + href: xref:Uno.Features.WSDisplay - name: Light Sensor - href: features/lightsensor.md + href: xref:Uno.Features.LightSensor - name: Magnetometer - href: features/magnetometer.md + href: xref:Uno.Features.Magnetometer - name: MIDI - href: features/windows-devices-midi.md + href: xref:Uno.Features.WDMidi - name: Network Information - href: features/windows-networking.md + href: xref:Uno.Features.WNetworking - name: Orientation Sensor - href: features/orientation-sensor.md + href: xref:Uno.Features.OrientationSensor - name: Package Information - href: features/windows-applicationmodel.md + href: xref:Uno.Features.WAM - name: Phone Calls - href: features/windows-applicationmodel-calls.md + href: xref:Uno.Features.WAMCalls - name: Proximity Sensor - href: features/proximity-sensor.md + href: xref:Uno.Features.ProximitySensor - name: Settings href: features/settings.md - name: Sharing - href: features/windows-applicationmodel-datatransfer.md + href: xref:Uno.Features.WAMDataTransfer - name: SMS - href: features/windows-applicationmodel-chat.md + href: xref:Uno.Features.WAMChat - name: Speech Recognition - href: features/SpeechRecognition.md + href: xref:Uno.Features.SpeechRecognition - name: Step Counter - href: features/step-counter.md + href: xref:Uno.Features.StepCounter - name: Store Context - href: features/windows-ui-storecontext.md + href: xref:Uno.Features.StoreContext - name: Title Bar Customization - href: features/windows-ui-viewmanagement.md + href: xref:Uno.Features.WinUIViewManagement - name: URI Launcher - href: features/windows-system.md + href: xref:Uno.Features.WS - name: Vibration - href: features/windows-phone-devices-notification-vibrationdevice.md + href: xref:Uno.Features.WPDNotification - name: Wallpaper and Lock Screen - href: features/windows-system-userprofile.md + href: xref:Uno.Features.WSUserProfile - name: Web Authentication Broker - href: features/web-authentication-broker.md + href: xref:Uno.Features.WAB - name: Working with cookies - href: features/working-with-cookies.md + href: xref:Uno.Features.Cookies - name: Extensions # topicHref: external/uno.extensions/doc/ExtensionsOverview.md @@ -722,7 +743,7 @@ href: xref:Uno.vscode.additional - name: C# Dev Kit Support href: xref:Uno.GetStarted.vscode.DevKit - - name: Omnisharp Support + - name: OmniSharp Support href: xref:Uno.GetStarted.vscode.OmniSharp - name: Rider items: @@ -731,8 +752,8 @@ - name: Templates items: - name: Visual Studio Wizard - href: getting-started/wizard/using-wizard.md + href: Uno.GettingStarted.UsingWizard - name: dotnet new Templates - href: get-started-dotnet-new.md + href: xref:Uno.GetStarted.dotnet-new - name: Get started wizard href: xref:Uno.GetStarted.Wizard diff --git a/doc/articles/Uno-UI-Performance.md b/doc/articles/uno-development/Uno-UI-Performance.md similarity index 100% rename from doc/articles/Uno-UI-Performance.md rename to doc/articles/uno-development/Uno-UI-Performance.md diff --git a/doc/articles/uno-development/Uno-UI-XAML-ResourceTrimming.md b/doc/articles/uno-development/Uno-UI-XAML-ResourceTrimming.md index b73167dadaa5..9f9fdf402a0e 100644 --- a/doc/articles/uno-development/Uno-UI-XAML-ResourceTrimming.md +++ b/doc/articles/uno-development/Uno-UI-XAML-ResourceTrimming.md @@ -4,7 +4,7 @@ uid: Uno.Contributing.XamlResourceTrimming # XAML Resource Trimming -This document provides technical details about the [XAML Resource trimming phase](../features/resources-trimming.md). +This document provides technical details about the [XAML Resource trimming phase](xref:Uno.Features.ResourcesTrimming). ## Technical Details @@ -35,7 +35,7 @@ As of Uno 3.9, the Uno.UI WebAssembly assembly is 7.5MB, trimmed down to 3.1MB f ## Using the `AdditionalLinkerHintAttribute` attribute -In some scenarios (e.g. ExpandoObject), it may be needed to generate linker hints for non-DependencyObject types. +In some scenarios (e.g. [ExpandoObject](https://learn.microsoft.com/en-us/dotnet/api/system.dynamic.expandoobject?view=net-9.0)), it may be needed to generate linker hints for non-DependencyObject types. To get a `__LinkerHints` property for an additional type, add the following in AssemblyInfo.cs: diff --git a/doc/articles/android-activities.md b/doc/articles/uno-development/android-activities.md similarity index 100% rename from doc/articles/android-activities.md rename to doc/articles/uno-development/android-activities.md diff --git a/doc/articles/uno-development/building-uno-macos.md b/doc/articles/uno-development/building-uno-macos.md deleted file mode 100644 index 72c3be78041d..000000000000 --- a/doc/articles/uno-development/building-uno-macos.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -uid: Uno.Contributing.BuildingUnomacOS ---- - -# Building Uno.UI for macOS using Visual Studio for Mac - -Building Uno.UI for the macOS platform using vs4mac requires Visual Studio for Mac 8.1 or later. - -Steps: - -* Make sure to [create the `crosstargeting_override.props` file](debugging-uno-ui.md) and set `UnoTargetFrameworkOverride` to `xamarinmac20`. - -* Open `Uno.UI-vs4mac.sln` to for iOS/Android/macOS heads or `Uno.UI-vs4mac-macOS-only.sln` for macOS only. - -* Set the `SamplesApp.macOS` project as the Startup Project. - -* Launch the application. - -Support for building the `Uno.UI` solution is still somewhat unstable, this is a list of known issues and troubleshooting steps: - -* You may get a message like `Error while trying to load the project '/Users/user/src/uno/build/Uno.UI.Build.csproj': Index has to be between upper and lower bound of the array.` when you open the solution. You can safely ignore this error. - -* If NuGet restore fails when building from the IDE, or if it gets stuck for some other reason, try building from the command line. Open a terminal session in the `uno/src` folder and use the following command: - - ```shell - msbuild /m /r SamplesApp/SamplesApp.macOS/SamplesApp.macOS.csproj - ``` - - Then reopen Visual Studio and try to launch the sample again. - -* If you get an error when building the `Uno.UI.Lottie` project complaining about typescript errors, you may need to install `Node.js` on your Mac. The easiest way to do this is to install the [Homebrew package manager](https://brew.sh/) and then use Homebrew to [install Node](https://changelog.com/posts/install-node-js-with-homebrew-on-os-x). - - **Beware: VS for Mac currently makes many unwanted "changes" to the `.csproj` files (like adding package version numbers explicitly, switching attributes to elements and vice-versa). Please do not commit these changes in your Pull Requests.** - -* Make sure to apply the workarounds specified in https://github.com/unoplatform/uno/issues/3609, otherwise VS4Mac will fail to load the solution. -* In order to successfully debug an external application, use [cross-targeting overrides](building-uno-ui.md#building-unoui-for-a-single-target-platform) and make sure to enable "Step into external code" in the "Projects / Debugger" options in VS4mac. diff --git a/doc/articles/composition.md b/doc/articles/uno-development/composition.md similarity index 100% rename from doc/articles/composition.md rename to doc/articles/uno-development/composition.md diff --git a/doc/articles/uno-development/debugging-inspect-visual-tree.md b/doc/articles/uno-development/debugging-inspect-visual-tree.md index 0b271f3ba3ea..0d9a3cfabec9 100644 --- a/doc/articles/uno-development/debugging-inspect-visual-tree.md +++ b/doc/articles/uno-development/debugging-inspect-visual-tree.md @@ -1,20 +1,24 @@ --- uid: Uno.Contributing.InspectVisualTree --- + + # Inspecting the runtime visual tree of an Uno app Often the first step in debugging a UI bug is to scrutinize the application's visual tree. The visual tree is derived from the app's layout defined in XAML, but there's not a straightforward 1-to-1 mapping from XAML to runtime visual tree, due to templating, view manipulation in code, etc. Also, by definition if you're getting a UI bug then there's a discrepancy between what you expect based on the XAML and code and the behavior you're actually observing. Don't live in suspense – check the visual tree! -Tools for inspecting the visual tree differ by platform. +## Inspection Tools per Platform -## UWP +Tools for inspecting the visual tree differ by platform: -UWP has by far the easiest and most convenient experience for debugging the visual tree. The small black toolbar at the top center of your app during debugging enable buttons to go to the Live Visual Tree view, directly select a visual element for inspection, and show layouting decorations. The complement to the Live Visual Tree is the Live Property Explorer, which allows you to inspect current values for any property of a view, and even change some of them on the fly. +# [UWP and WinUI](#tab/uwp-winui) + +UWP and WinUI having by far the easiest and most convenient experience for debugging the visual tree. The small black toolbar at the top center of your app during debugging enable buttons to go to the Live Visual Tree view, directly select a visual element for inspection, and show layouting decorations. The complement to the Live Visual Tree is the Live Property Explorer, which allows you to inspect current values for any property of a view, and even change some of them on the fly. ![UWP Live Visual Tree](assets/debugging-inspect-visual-tree/UWP-Live-Visual-Tree.jpg) -## Android +# [Android](#tab/android) There are a couple of options for viewing the visual tree of an Uno app running on Android. @@ -26,7 +30,7 @@ The other approach is to use the [Stetho package](https://www.nuget.org/packages Unfortunately neither of these approaches give you an easy way to inspect properties defined on UIElement, FrameworkElement, and other managed types. You can however look at native properties to obtain information like layout size, opacity, etc. -## iOS +# [iOS](#tab/ios) In principle it's possible to use Xcode's 'Debug View Hierarchy' feature on any iOS app, including Uno apps. The steps are the following: @@ -34,12 +38,12 @@ In principle it's possible to use Xcode's 'Debug View Hierarchy' feature on any 2. Create a dummy iOS app (or open an existing one) - you won't actually run this app. 3. Run the app whose layout you wish to inspect. 4. Set the device or simulator you're using as the active device in the upper toolbar. -5. Select Debug -> Attach to Process -> [name of the app] +5. Select Debug -> Attach to Process -> `[name of the app]` 6. Once the debugger has successfully attached, select Debug -> View Debugging -> Capture View Hierarchy. In practice, Xcode is somewhat temperamental, and this approach may fail for some apps. It's recommended to fall back on the breakpoint-based inspection method described below. -## Web +# [Web](#tab/web) For an Uno.WASM app you can simply use the layout inspection tools built into whatever browser you're using. For example, for Chrome, open the 'Developer tools' panel (`F12`) and select the 'Elements' tab, or just right-click any element in the visual tree and choose 'Inspect.' @@ -58,13 +62,15 @@ You can configure Uno to annotate the DOM with the values of common XAML propert **Note:** for performance reasons, if a _release build_ of Uno.UI is used, `AssignDOMXamlProperties` will only display the values of properties as they were when the element was loaded - that is, they may be stale in some cases. If a _debug build_ of Uno.UI is used, this limitation is lifted and the DOM annotation will reflect the most up-to-date values. +--- + ## Retrieving the visual tree through code or at a breakpoint (Android/iOS/WebAssembly/macOS) It's common enough when debugging Uno to be at a breakpoint and want to quickly know exactly where the view is in the visual tree, that we added a helper method. -If you're using a debug build of Uno, this is directly available on UIElement as the `public string ShowLocalVisualTree(int fromHeight)` method (for ease of use in the watch window). If you're using the release version of Uno, the same method is available as an extension in UIKit.UIViewExtensions for iOS or Uno.UI.ViewExtensions for Android. +If you're using a debug build of Uno, this is directly available on UIElement as the `public string ShowLocalVisualTree(int fromHeight)` method (for ease of use in the watch window). If you're using the release version of Uno, the same method is available as an extension in `UIKit.UIViewExtensions` for iOS or `Uno.UI.ViewExtensions` for Android. -The method returns the visual tree from a certain 'height' above the target element as an indented string. So if you call ShowLocalVisualTree(2), you'll get the visual subtree from the target element's grandparent down. If you call ShowLocalVisualTree(100), you'll almost certainly get the entire visual tree starting from the root element. The original target is picked out with an asterisk (*) so you can find it. +The method returns the visual tree from a certain 'height' above the target element as an indented string. So if you call `ShowLocalVisualTree(2)`, you'll get the visual subtree from the target element's grandparent down. If you call `ShowLocalVisualTree(100)`, you'll almost certainly get the entire visual tree starting from the root element. The original target is picked out with an asterisk (*) so you can find it. ![ShowLocalVisualTree() on iOS](assets/debugging-inspect-visual-tree/iOS-ShowLocalVisualTree.jpg) @@ -88,7 +94,7 @@ The advantage of this over `ShowLocalVisualTree` is the ability to customize the > For more examples of control details, check out these source files: > > - [`DebugVTNode\GetDetails()` method in Toolkit](https://github.com/unoplatform/uno.toolkit.ui/blob/main/src/Uno.Toolkit.UI/Helpers/VisualTreeHelperEx.cs) -> - [`DescribeVTNode\GetDetails()` method in Uno](https://github.com/unoplatform/uno/blob/master/src/Uno.UI/Extensions/ViewExtensions.visual-tree.cs) +> - [`DescribeVTNode\GetDetails()` method in Uno](../../../src/Uno.UI/Extensions/ViewExtensions.visual-tree.cs) ```csharp var tree = this.TreeGraph(Describe); diff --git a/doc/articles/debugging-wasm.md b/doc/articles/uno-development/debugging-wasm.md similarity index 89% rename from doc/articles/debugging-wasm.md rename to doc/articles/uno-development/debugging-wasm.md index f53e136a6524..2a078fb6a43f 100644 --- a/doc/articles/debugging-wasm.md +++ b/doc/articles/uno-development/debugging-wasm.md @@ -13,7 +13,7 @@ There are two ways to debug a WebAssembly application: Here’s what you need to do to debug an Uno Platform application in Visual Studio (2022 17.1 or later): -- Install the latest [Uno Platform Visual Studio templates](./get-started-vs-2022.md#install-the-solution-templates) +- Install the latest [Uno Platform Visual Studio Extension](getting-started/get-started-vs-2022.md#install-the-uno-platform-extension) - Have Chrome or Edge (Chromium based) - In the NuGet Package Manager, update `Uno.Wasm.Bootstrap` and `Uno.Wasm.Bootstrap.DevServer` 8.0.0 or later - Ensure that `true` is set in your csproj. It is automatically set [when using the Uno.SDK](xref:Uno.Features.Uno.Sdk). @@ -48,16 +48,16 @@ To debug your application: - Select **MyApp (WebAssembly IIS Express)** as the debugging target - Select **Chrome** or **Microsoft Edge** as the Web Browser - Make sure script debugging is disabled
- ![IIS express settings](Assets/quick-start/wasm-debugging-iis-express.png) + ![IIS express settings](getting-started/Assets/quick-start/wasm-debugging-iis-express.png) - Start the debugging session using CtrlF5 or _Debug_ > _Start Without Debugging_ from the menu, (F5 will work, but the debugging experience won't be in Visual Studio) - Once your application has started, press AltShiftD (in Chrome, on your application's tab) - A new tab will open with the debugger or instructions to activate it -![Debugger - New tab with instructions to activate it](Assets/quick-start/wasm-debugger-step-01.png) +![Debugger - New tab with instructions to activate it](getting-started/Assets/quick-start/wasm-debugger-step-01.png) - You will now get the Chrome DevTools to open listing all the .NET loaded assemblies on the Sources tab:
-![Debugger - Chrome DevTools listing all the .NET loaded assemblies on the Sources tab](Assets/quick-start/wasm-debugger-step-02.png) +![Debugger - Chrome DevTools listing all the .NET loaded assemblies on the Sources tab](getting-started/Assets/quick-start/wasm-debugger-step-02.png) - You may need to refresh the original tab if you want to debug the entry point (Main) of your application.
-![Debugger - The smaller refresh button location in the preview section of the Chrome DevTools](Assets/quick-start/wasm-debugger-step-03.png) +![Debugger - The smaller refresh button location in the preview section of the Chrome DevTools](getting-started/Assets/quick-start/wasm-debugger-step-03.png) > ### Tips for debugging in Chrome > diff --git a/doc/articles/uno-development/docfx.md b/doc/articles/uno-development/docfx.md deleted file mode 100644 index e82a778d88c4..000000000000 --- a/doc/articles/uno-development/docfx.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -uid: Uno.Contributing.DocFx ---- - - - -# The Uno docs website and DocFX - -Uno Platform's docs website uses [DocFX](https://dotnet.github.io/docfx/) to convert Markdown files in the [articles folder](https://github.com/unoplatform/uno/tree/master/doc/articles) into [html files](xref:Uno.Documentation.Intro). - -## Adding to the table of contents - -Normally when you add a new doc file, you also add it to [articles/toc.yml](https://github.com/unoplatform/uno/blob/master/doc/articles/toc.yml). This allows it to show up in the left sidebar Table of Contents on the docs website. - -## DocFX-flavored Markdown - -DocFX supports extended Markdown syntaxes that are treated specially when converting to html. - -### Formatted blockquotes - -You can declare a [specially-styled blockquote](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#note-warningtipimportant) like so: - -```md -> [!NOTE] -> This is a Note, showing how to declare notes. -``` - -This is how it looks when converted to .html: - -> [!NOTE] -> This is a Note, showing how to declare notes. - -Use pre-formatted blockquotes when you want to call special attention to particular information. - -The following note types are supported: - -```md -> [!NOTE] -> ... - -> [!TIP] -> ... - -> [!WARNING] -> ... - -> [!IMPORTANT] -> ... - -> [!CAUTION] -> ... - -``` - -### Tabs - -DocFX can generate tabs. Make sure to follow the [syntax specification](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#tabbed-content) precisely. - -#### Example - -Markdown: - -```md -# [WinUI](#tab/tabid-1) - -`Microsoft.UI.Xaml.FrameworkElement` - -# [UWP](#tab/tabid-2) - -`Windows.UI.Xaml.FrameworkElement` - ---- -``` - -Html output: - -# [WinUI](#tab/tabid-1) - -`Microsoft.UI.Xaml.FrameworkElement` - -# [UWP](#tab/tabid-2) - -`Windows.UI.Xaml.FrameworkElement` - ---- - -### TOC checker script - -The [`check_toc` script](https://github.com/unoplatform/uno/blob/master/doc/articles/check_toc.ps1) checks for dead links in the TOC, as well as Markdown files in the 'articles' folder that are not part of the TOC. At the moment it's not part of the CI, but contributors can run it locally and fix any bad or missing links. - - - -## Building docs website locally with DocFX - -Sometimes you may want to run DocFX locally to validate that changes you've made look good in html. To do so you'll first need to generate the 'implemented views' documentation. - -### Run DocFX locally - -To run DocFX locally and check the resulting html: - -1. Open the `Uno.UI-Tools.slnf` solution filter in the `src` folder with Visual Studio. -2. Edit the properties of the `Uno.UwpSyncGenerator` project. Under the 'Debug' tab, set Application arguments to "doc". -3. Set `Uno.UwpSyncGenerator` as startup project and run it. It may fail to generate the full implemented views content; if so, it should still nonetheless generate stubs so that DocFX can run successfully. -4. Navigate to `%USERPROFILE%\.nuget\packages\docfx.console`. If you don't see the DocFX package in your NuGet cache, go back to ``Uno.UI-Tools.slnf`, right-click on the solution and choose 'Restore NuGet Packages.' -5. Open the latest DocFX version and open the `tools` folder. -6. Open a Powershell window in the `tools` folder. -7. Run the following command: `.\docfx "C:\src\Uno.UI\doc\docfx.json" -o C:\src\Uno.UI\docs-local-dist`, replacing `C:\src\Uno.UI` with your local path to the Uno.UI repository. -8. When DocFX runs successfully, it will create the html output at `C:\src\Uno.UI\docs-local-dist\_site`, which you can now view or mount on a local server. - -### Use a local server - -You can use `dotnet-serve` as a simple command-line HTTP server for example. - -1. Install `dotnet-serve` using the following command: `dotnet tool install --global dotnet-serve`. For more info about its usage and options, -[please refer to the documentation](https://github.com/natemcmaster/dotnet-serve). -2. Using the command prompt, navigate to `C:\src\Uno.UI\docs-local-dist\_site` (replacing `C:\src\Uno.UI` with your local path to the Uno.UI repository) and run the following command `dotnet serve -o -S`. This will start a simple server with HTTPS and open the browser directly. - -## Run the documentation generation performance test - -If needed, you can also run a script that will give you a performance summary for the documentation generation. - -To run the script on Windows: - -1. Make sure `crosstargeting_override.props` is not defining UnoTargetFrameworkOverride -2. Open a Developer Command Prompt for Visual Studio (2019 or 2022) -3. Go to the uno\build folder (not the uno\src\build folder) -4. Run the `run-doc-generation.cmd` script; make sure to follow the instructions diff --git a/doc/articles/how-uno-works.md b/doc/articles/uno-development/how-uno-works.md similarity index 99% rename from doc/articles/how-uno-works.md rename to doc/articles/uno-development/how-uno-works.md index 83960269629b..c431d36994f3 100644 --- a/doc/articles/how-uno-works.md +++ b/doc/articles/uno-development/how-uno-works.md @@ -16,7 +16,7 @@ The rest of this article discusses how the Uno.UI tooling allows WinUI-compatibl The [`Uno.WinUI` NuGet package](https://www.nuget.org/packages/Uno.WinUI/) completely reproduces the WinUI API surface: all namespaces (`Microsoft.UI.Xaml`, `Windows.Foundation`, `Windows.Storage`, etc), all classes, all class members. Insofar as possible, the same look and behavior as on Windows are replicated on all other platforms. -Note that, as the API surface is very large, some parts are included but not implemented. These features are marked with the `Uno.NotImplementedAttribute` attribute, and a code analyzer is included with the Uno.WinUI package will generate a warning for any such features that are referenced. You can see a complete list of supported APIs [here](implemented-views.md). +Note that, as the API surface is very large, some parts are included but not implemented. These features are marked with the `Uno.NotImplementedAttribute` attribute, and a code analyzer is included with the Uno.WinUI package will generate a warning for any such features that are referenced. You can see a complete list of supported APIs [here](../implemented-views.md). ## How the UI is rendered diff --git a/doc/articles/uno-development/interaction-tracker-internals.md b/doc/articles/uno-development/interaction-tracker-internals.md index 8af44ef1427c..80e0a791d780 100644 --- a/doc/articles/uno-development/interaction-tracker-internals.md +++ b/doc/articles/uno-development/interaction-tracker-internals.md @@ -1,3 +1,6 @@ +--- +uid: Uno.Contributing.InteractionTracker +--- # InteractionTracker internals This document tries to detail and clarify the implementation of InteractionTracker. diff --git a/doc/articles/native-styles.md b/doc/articles/uno-development/native-styles.md similarity index 100% rename from doc/articles/native-styles.md rename to doc/articles/uno-development/native-styles.md diff --git a/doc/articles/native-views.md b/doc/articles/uno-development/native-views.md similarity index 100% rename from doc/articles/native-views.md rename to doc/articles/uno-development/native-views.md diff --git a/doc/articles/supported-libraries.md b/doc/articles/uno-development/supported-libraries.md similarity index 100% rename from doc/articles/supported-libraries.md rename to doc/articles/uno-development/supported-libraries.md diff --git a/doc/articles/uno-toolchain-telemetry.md b/doc/articles/uno-development/uno-toolchain-telemetry.md similarity index 100% rename from doc/articles/uno-toolchain-telemetry.md rename to doc/articles/uno-development/uno-toolchain-telemetry.md diff --git a/doc/articles/using-uno-ui.md b/doc/articles/using-uno-ui.md index 08873d8262da..11b5686bc0fe 100644 --- a/doc/articles/using-uno-ui.md +++ b/doc/articles/using-uno-ui.md @@ -69,3 +69,11 @@ Uno Platform supports a number of non-visual APIs from Windows Runtime namespace * [Hot Reload](xref:Uno.Features.HotReload) * [Troubleshooting build errors](uno-builds-troubleshooting.md) * [Debugging C# on WASM](debugging-wasm.md) + +## IDE Specifics + +### Visual Studio Code + +* [Explore Commands and Snippets provided by the VS Code Extension](xref:Uno.vscode.additional) +* [Common Issues VS Code](xref:Uno.UI.CommonIssues.vscode) +* [Updating an existing application to work with VS Code](xref:Uno.vscode.additional#updating-an-existing-application-to-work-with-vs-code) diff --git a/doc/articles/winui-doc-links-tutorials.md b/doc/articles/winui-doc-links-tutorials.md index 707c1bf26282..b9993f876925 100644 --- a/doc/articles/winui-doc-links-tutorials.md +++ b/doc/articles/winui-doc-links-tutorials.md @@ -6,7 +6,7 @@ uid: Uno.Development.WinUITutorialsDoc Uno Platform's API is derived from the WinUI application framework. Microsoft provides [extensive documentation for WinUI](https://learn.microsoft.com/windows/uwp/). Rather than duplicate all of it, here we list selected entries that are especially applicable to Uno Platform developers. -You can work through these tutorials either as single-platform UWP applications or as multi-platform Uno Platform applications. In the latter case, when the tutorial instructs you to create a new UWP application in Visual Studio, you should create a [new Uno Platform application](get-started.md) instead. +You can work through these tutorials either as single-platform UWP applications or as multi-platform Uno Platform applications. In the latter case, when the tutorial instructs you to create a new UWP application in Visual Studio, you should create a [new Uno Platform application](xref:Uno.GetStarted) instead. * [Navigate between two pages](https://learn.microsoft.com/windows/uwp/design/basics/navigate-between-two-pages) * [Create a simple weather app with Grid and StackPanel](https://learn.microsoft.com/windows/uwp/design/layout/grid-tutorial) diff --git a/doc/articles/winui-doc-links.md b/doc/articles/winui-doc-links.md index 1adfa709e69f..003109d53bad 100644 --- a/doc/articles/winui-doc-links.md +++ b/doc/articles/winui-doc-links.md @@ -6,7 +6,7 @@ uid: Uno.Development.WinUIDoc Uno Platform's API is derived from the WinUI application framework. Microsoft provides [extensive documentation for WinUI](https://learn.microsoft.com/windows/uwp/). Rather than duplicate all of it, here we list selected entries that are especially applicable to Uno Platform developers. -Note that some instructions may not apply when using Uno Platform. For example: some articles will instruct you to create a new UWP application in Visual Studio - you would in that case [create a new Uno Platform application](get-started.md) instead. +Note that some instructions may not apply when using Uno Platform. For example: some articles will instruct you to create a new UWP application in Visual Studio - you would in that case [create a new Uno Platform application](xref:Uno.GetStarted) instead. * [Tutorials](winui-doc-links-tutorials.md) * [Development](winui-doc-links-development.md) diff --git a/doc/blog/201809-UnoUnderTheHoodXamlGeneration.md b/doc/blog/201809-UnoUnderTheHoodXamlGeneration.md index 2868a6c129a5..975296d8ea3e 100644 --- a/doc/blog/201809-UnoUnderTheHoodXamlGeneration.md +++ b/doc/blog/201809-UnoUnderTheHoodXamlGeneration.md @@ -85,5 +85,3 @@ What a mouthful! Bear in mind that generated code tends to be optimized for mach In the normal course of Uno development you don't need to look at code generated from XAML or even know that it's there, though occasionally it's useful to take a peek when debugging. You can see that something called `Button_Click` is subscribed to the Button's Click event. Recall that `Button_Click` is defined in [the code-behind](https://medium.com/@unoplatform/pushing-the-right-buttons-how-uno-implements-views-under-the-hood-a5e93ea86688#the-number-goes-up) in `MainPage.xaml.cs`. As far as the compiler is concerned, both the authored and generated files are just [partial definitions](https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods) of the same class. - -One last fun fact: when building on macOS using [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/) (which Uno tentatively supports in preview), Uno uses an internal port in place of the System.Xaml namespace which isn't available on Mac. The same code backs Uno's support for runtime Xaml interpretation via [Windows.UI.Xaml.Markup.XamlReader](https://learn.microsoft.com/uwp/api/windows.ui.xaml.markup.xamlreader). That in turn is used in the [interactive mode](https://github.com/unoplatform/uno.Playground/blob/master/src/Uno.Playground.Shared/Samples/Playground.xaml) of the [Uno Gallery app](https://github.com/unoplatform/uno.Playground) and [Uno.Playground website](https://playground.platform.uno/), which allows you to edit snippets of XAML and see the results in realtime. Check it out!