diff --git a/.github/workflows/prefill-pr.yml b/.github/workflows/prefill-pr.yml index 950badfa..6323a164 100644 --- a/.github/workflows/prefill-pr.yml +++ b/.github/workflows/prefill-pr.yml @@ -26,7 +26,10 @@ jobs: const yamatoBadge = "[![Yamato CI](https://img.shields.io/badge/Yamato-CI-blue?logo=unity&logoColor=white)](" + yamatoUrl + ")"; - const buttons = MARKER + "\n" + yamatoBadge + "\n" + MARKER; + const docsUrl = "https://yamato.ds.unity3d.com/project/277/branch/" + branch + "/jobDefinition/.yamato%2Fdocs.yml%23build_docs"; + const docsBadge = "[![Docs preview](https://img.shields.io/badge/Docs-preview-green?logo=readthedocs&logoColor=white)](" + docsUrl + ")"; + + const buttons = MARKER + "\n" + yamatoBadge + " " + docsBadge + "\n" + MARKER; await github.rest.pulls.update({ owner: context.repo.owner, diff --git a/.yamato/docs.yml b/.yamato/docs.yml new file mode 100644 index 00000000..4320bf9d --- /dev/null +++ b/.yamato/docs.yml @@ -0,0 +1,32 @@ +build_docs: + name: Preview documentation + agent: + type: Unity::VM + image: unity-docs-engineering/packagedocs-cli-build:latest + flavor: b1.large + variables: + # Without it the CLI takes package-manager-doctools at HEAD, so its changes could break this job. + DOCTOOLS_REVISION: stable + commands: + - command: npm install -g @docs-tools/packagedocs-cli --@docs-tools:registry=https://artifactory.prd.it.unity3d.com/artifactory/api/npm/docs-tools-npm/ + timeout: 20 + retries: 5 + # Without --unity-editor the CLI installs the Editor version from package.json itself. + # The status path must be absolute: the Editor resolves it against its own temporary project. + - command: packagedocs-cli build --package-path com.unity.mobile.android-logcat --output docs~ --built-in-code-project-gen --validate --path-to-pmdt-status-output %YAMATO_SOURCE_DIR%\pmdt_status.json + - command: copy .yamato\docs\preview-docs.* docs~\ + - command: .yamato\docs\write-index.bat + artifacts: + # To view the docs, run docs~/preview-docs.bat (Windows) or `sh docs~/preview-docs.sh` (macOS, Linux) from the downloaded zip. + docs: + paths: + - "docs~/**/*" + # Unzip the docs as soon as the job ends, so the artifact viewer can serve them without a manual Unzip. + browsable: always + logs: + paths: + - "UnityEditor.log" + - "pmdt_status.json" + triggers: + cancel_old_ci: true + expression: pull_request.target eq "master" AND (pull_request.changes.any match "com.unity.mobile.android-logcat/Documentation~/**/*" OR pull_request.changes.any match "com.unity.mobile.android-logcat/**/*.cs") diff --git a/.yamato/docs/preview-docs.bat b/.yamato/docs/preview-docs.bat new file mode 100644 index 00000000..ded358a9 --- /dev/null +++ b/.yamato/docs/preview-docs.bat @@ -0,0 +1,10 @@ +@echo off +rem Serves the docs over HTTP: DocFX loads the sidebar with a request that browsers block for pages opened from disk. +where python >nul 2>&1 || (echo Python is required to serve the docs. & pause & exit /b 1) + +cd /d "%~dp0documentation" +for /d %%d in (com.unity.mobile.android-logcat@*) do if /i not "%%d"=="com.unity.mobile.android-logcat@latest" set DOCS=%%d + +start "" /b python -c "import time, webbrowser; time.sleep(1); webbrowser.open('http://localhost:8000/%DOCS%/manual/index.html')" +echo Serving %DOCS% at http://localhost:8000, close this window to stop. +python -m http.server 8000 diff --git a/.yamato/docs/preview-docs.sh b/.yamato/docs/preview-docs.sh new file mode 100755 index 00000000..6ee40ef2 --- /dev/null +++ b/.yamato/docs/preview-docs.sh @@ -0,0 +1,13 @@ +#!/bin/sh +# Serves the docs over HTTP: DocFX loads the sidebar with a request that browsers block for pages opened from disk. +command -v python3 >/dev/null 2>&1 || { echo "Python 3 is required to serve the docs."; exit 1; } + +cd "$(dirname "$0")/documentation" || exit 1 +for d in com.unity.mobile.android-logcat@*; do + if [ "$d" != "com.unity.mobile.android-logcat@latest" ]; then DOCS=$d; fi +done + +URL="http://localhost:8000/$DOCS/manual/index.html" +(sleep 1; if command -v open >/dev/null 2>&1; then open "$URL"; else xdg-open "$URL"; fi) & +echo "Serving $DOCS at http://localhost:8000, press Ctrl+C to stop." +python3 -m http.server 8000 diff --git a/.yamato/docs/write-index.bat b/.yamato/docs/write-index.bat new file mode 100644 index 00000000..e90aef41 --- /dev/null +++ b/.yamato/docs/write-index.bat @@ -0,0 +1,15 @@ +@echo off +rem Writes docs~/index.html, a fixed entry point that redirects to the manual of the version just built. +cd /d "%~dp0..\..\docs~\documentation" || exit /b 1 +for /d %%d in (com.unity.mobile.android-logcat@*) do if /i not "%%d"=="com.unity.mobile.android-logcat@latest" set DOCS=%%d +if not defined DOCS (echo No generated docs found in docs~\documentation. & exit /b 1) + +set TARGET=documentation/%DOCS%/manual/index.html +( + echo ^ + echo ^ + echo ^ + echo ^%DOCS% documentation^ + echo ^Open the %DOCS% documentation^ +) > ..\index.html +echo Wrote docs~\index.html pointing at %TARGET% diff --git a/com.unity.mobile.android-logcat/Documentation~/android-logcat-window-reference.md b/com.unity.mobile.android-logcat/Documentation~/android-logcat-window-reference.md index 307708f3..7464473e 100644 --- a/com.unity.mobile.android-logcat/Documentation~/android-logcat-window-reference.md +++ b/com.unity.mobile.android-logcat/Documentation~/android-logcat-window-reference.md @@ -67,6 +67,9 @@ You can access the **Process Manager** from the message log section when you rig The following options in the **Process Manager** help you to force an application to terminate. +![Send Unix signal options in the Process Manager](images/android-logcat-send-unix-signal.png) +> Send Unix signal options. + | **Type** | **Description** | | - | - | | **Send Unix signal** | Sends a signal to the process using command **adb shell run-as kill -s **. For more information, refer to [standard signals](https://man7.org/linux/man-pages/man7/signal.7.html).

You can use **SIGILL**, **SIGTRAP**, **SIGABRT**, **SIGBUS**, **SIGFPE**, **SIGSEGV**, **SIGPIPE**, **SIGSTKFLT** signals to test Unity Android [crash handler](https://docs.unity3d.com/Manual/android-handle-crashes.html). | @@ -77,6 +80,9 @@ The following options in the **Process Manager** help you to force an applicatio The **Send Trim Memory** option allows you to send a memory trim signal to the selected process to help you understand how your application handles low memory events. The control sends a memory trim event to a process using command **adb shell am send-trim-memory **. For more information about the trim levels, refer to [Android developer documentation](https://developer.android.com/reference/android/content/ComponentCallbacks2#constants_1). +![Send Trim Memory options in the Process Manager](images/android-logcat-app-trim-memory.png) +> Send Trim Memory options. + For example, by using **RUNNING_CRITICAL** trim level you can test the following Unity APIs: * [Application.lowMemory](https://docs.unity3d.com/ScriptReference/Application-lowMemory.html) * [Application.memoryUsageChanged](https://docs.unity3d.com/ScriptReference/Application-memoryUsageChanged.html) diff --git a/com.unity.mobile.android-logcat/Documentation~/connect-to-a-device.md b/com.unity.mobile.android-logcat/Documentation~/connect-to-a-device.md index 0853d2b0..266cf6ce 100644 --- a/com.unity.mobile.android-logcat/Documentation~/connect-to-a-device.md +++ b/com.unity.mobile.android-logcat/Documentation~/connect-to-a-device.md @@ -20,7 +20,7 @@ To connect an Android device to the Android Logcat window: 4. Select **Other connection options**. 5. In window that opens, enter the device's IP address and select **Connect**. -![The available devices window displaying connected devices](images/AndroidLogcatIPWindow.png) +![The available devices window displaying connected devices](images/android-logcat-ip-window.png) > The available devices window. ## Select a device diff --git a/com.unity.mobile.android-logcat/Documentation~/images/MemoryWindowCapture.png b/com.unity.mobile.android-logcat/Documentation~/images/MemoryWindowCapture.png deleted file mode 100644 index 6d2d7bdc..00000000 Binary files a/com.unity.mobile.android-logcat/Documentation~/images/MemoryWindowCapture.png and /dev/null differ diff --git a/com.unity.mobile.android-logcat/Documentation~/images/android-logcat-app-trim-memory.png b/com.unity.mobile.android-logcat/Documentation~/images/android-logcat-app-trim-memory.png index 64d273a3..16a2dcf9 100644 Binary files a/com.unity.mobile.android-logcat/Documentation~/images/android-logcat-app-trim-memory.png and b/com.unity.mobile.android-logcat/Documentation~/images/android-logcat-app-trim-memory.png differ diff --git a/com.unity.mobile.android-logcat/Documentation~/images/AndroidLogcatIPWindow.png b/com.unity.mobile.android-logcat/Documentation~/images/android-logcat-ip-window.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/AndroidLogcatIPWindow.png rename to com.unity.mobile.android-logcat/Documentation~/images/android-logcat-ip-window.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_Cursor.png b/com.unity.mobile.android-logcat/Documentation~/images/inputs-window-cursor.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_Cursor.png rename to com.unity.mobile.android-logcat/Documentation~/images/inputs-window-cursor.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_Keyboard.png b/com.unity.mobile.android-logcat/Documentation~/images/inputs-window-keyboard.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_Keyboard.png rename to com.unity.mobile.android-logcat/Documentation~/images/inputs-window-keyboard.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_Media.png b/com.unity.mobile.android-logcat/Documentation~/images/inputs-window-media.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_Media.png rename to com.unity.mobile.android-logcat/Documentation~/images/inputs-window-media.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_Misc.png b/com.unity.mobile.android-logcat/Documentation~/images/inputs-window-misc.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_Misc.png rename to com.unity.mobile.android-logcat/Documentation~/images/inputs-window-misc.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_Numpad.png b/com.unity.mobile.android-logcat/Documentation~/images/inputs-window-numpad.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_Numpad.png rename to com.unity.mobile.android-logcat/Documentation~/images/inputs-window-numpad.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_SendText.png b/com.unity.mobile.android-logcat/Documentation~/images/inputs-window-send-text.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_SendText.png rename to com.unity.mobile.android-logcat/Documentation~/images/inputs-window-send-text.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_TV.png b/com.unity.mobile.android-logcat/Documentation~/images/inputs-window-tv.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/InputsWindow_TV.png rename to com.unity.mobile.android-logcat/Documentation~/images/inputs-window-tv.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/InputsWindow.png b/com.unity.mobile.android-logcat/Documentation~/images/inputs-window.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/InputsWindow.png rename to com.unity.mobile.android-logcat/Documentation~/images/inputs-window.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/label-c.png b/com.unity.mobile.android-logcat/Documentation~/images/label-c.png deleted file mode 100644 index e6607aa9..00000000 Binary files a/com.unity.mobile.android-logcat/Documentation~/images/label-c.png and /dev/null differ diff --git a/com.unity.mobile.android-logcat/Documentation~/images/MemoryDump.png b/com.unity.mobile.android-logcat/Documentation~/images/memory-dump.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/MemoryDump.png rename to com.unity.mobile.android-logcat/Documentation~/images/memory-dump.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/MemoryGroups.png b/com.unity.mobile.android-logcat/Documentation~/images/memory-groups.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/MemoryGroups.png rename to com.unity.mobile.android-logcat/Documentation~/images/memory-groups.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/MemoryWindowChart.png b/com.unity.mobile.android-logcat/Documentation~/images/memory-window-chart.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/MemoryWindowChart.png rename to com.unity.mobile.android-logcat/Documentation~/images/memory-window-chart.png diff --git a/com.unity.mobile.android-logcat/Documentation~/images/MemoryWindow.png b/com.unity.mobile.android-logcat/Documentation~/images/memory-window.png similarity index 100% rename from com.unity.mobile.android-logcat/Documentation~/images/MemoryWindow.png rename to com.unity.mobile.android-logcat/Documentation~/images/memory-window.png diff --git a/com.unity.mobile.android-logcat/Documentation~/inputs-window.md b/com.unity.mobile.android-logcat/Documentation~/inputs-window.md index fd81378a..cf07e561 100644 --- a/com.unity.mobile.android-logcat/Documentation~/inputs-window.md +++ b/com.unity.mobile.android-logcat/Documentation~/inputs-window.md @@ -6,7 +6,7 @@ To open the Inputs window in the Unity Editor: 1. Open the [Android Logcat window](android-logcat-window.md). 2. In the [Toolbar](android-logcat-window-reference.md#toolbar), select **Tools** > **Window** > **Inputs**. -![The inputs window](images/inputswindow.png) +![The inputs window](images/inputs-window.png) The inputs window is divided into five sections: * Keyboard keys @@ -22,7 +22,7 @@ The inputs window is divided into five sections: ## Keyboard keys -![The inputs window keyboard](images/InputsWindow_Keyboard.png) +![The inputs window keyboard](images/inputs-window-keyboard.png) Includes letter, number, punctuation, symbol, function, and control keys. @@ -32,19 +32,19 @@ You can select **Shift** modifier to send keys as if while holding shift. ## Cursor keys -![Cursor keys](images/InputsWindow_Cursor.png) +![Cursor keys](images/inputs-window-cursor.png) Includes navigation keys. ## Numpad keys -![Numpad keys](images/InputsWindow_Numpad.png) +![Numpad keys](images/inputs-window-numpad.png) Includes numerical keys. ## Miscellaneous keys -![Miscellaneous keys](images/InputsWindow_Misc.png) +![Miscellaneous keys](images/inputs-window-misc.png) Includes various helper keys for Android: * Volume keys @@ -59,18 +59,18 @@ Includes various helper keys for Android: * Back/Home/Menu ## TV keys -![TV keys](images/InputsWindow_TV.png) +![TV keys](images/inputs-window-tv.png) Incluse basic TV keys. ## Media -![Media keys](images/InputsWindow_Media.png) +![Media keys](images/inputs-window-media.png) Incluse basic Media keys. ## Send text - ![Send block of text](images/InputsWindow_SendText.png) + ![Send block of text](images/inputs-window-send-text.png) Provides functionality for send block of text to Android device. \ No newline at end of file diff --git a/com.unity.mobile.android-logcat/Documentation~/memory-window-reference.md b/com.unity.mobile.android-logcat/Documentation~/memory-window-reference.md index 24f3e06b..3f903ad1 100644 --- a/com.unity.mobile.android-logcat/Documentation~/memory-window-reference.md +++ b/com.unity.mobile.android-logcat/Documentation~/memory-window-reference.md @@ -9,7 +9,7 @@ To open the Memory window in the Unity Editor: If you select **Auto Capture**, Unity periodically captures memory snapshots for the selected application. If you deselect **Auto Capture**, the memory window provides a **Capture** button which you can use to manually capture a memory snapshot. This is useful if the automatic memory requests affect the application's performance. -![The memory window](images/MemoryWindow.png) +![The memory window](images/memory-window.png) > The memory window. | **Label** | **Description** | @@ -34,6 +34,9 @@ The memory details panel displays the amount of memory for each memory type. It The Memory window can display different memory groups allocated for your application. +![The memory group drop-down](images/memory-groups.png) +> The memory group drop-down. + | **Memory group** | **Description** | | ------------------------------- | ------------------------------------------------------------ | | **Resident Set Size (RSS)** | The total amount of memory in RAM that the application allocated. This includes both shared and non-shared memory pages. For example, applications that access the same library share memory pages.
**Note**: This metric is only visible on Android 11 or higher. | @@ -60,14 +63,14 @@ To make memory requests, the Memory window uses `adb shell dumpsys meminfo packa The following screenshot shows the memory dump that `dumpsys` produces: -![A raw dumpsys memory dump](images/MemoryDump.png) +![A raw dumpsys memory dump](images/memory-dump.png) > A raw `dumpsys` memory dump. ## Memory chart The memory chart displays the memory allocated for the connected application over time. - ![The memory chart](images/MemoryWindowChart.png) + ![The memory chart](images/memory-window-chart.png) > The memory chart. To view a snapshot in the [memory details panel](#memory-details-panel), click on the chart at the part you want to view. diff --git a/com.unity.mobile.android-logcat/Tests/Editor/AndroidLogcatDocumentationTests.cs b/com.unity.mobile.android-logcat/Tests/Editor/AndroidLogcatDocumentationTests.cs new file mode 100644 index 00000000..7d4adb89 --- /dev/null +++ b/com.unity.mobile.android-logcat/Tests/Editor/AndroidLogcatDocumentationTests.cs @@ -0,0 +1,95 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Text.RegularExpressions; +using NUnit.Framework; +using Unity.Android.Logcat; + +class AndroidLogcatDocumentationTests +{ + static readonly string[] kImageExtensions = { ".png", ".jpg", ".jpeg", ".gif", ".svg" }; + + // ![alt](path "title") and + static readonly Regex kImageReference = new Regex( + @"!\[[^\]]*\]\(\s*[^)\s>]+)>?(?:\s+""[^""]*"")?\s*\)|]*src\s*=\s*[""'](?[^""']+)[""']", + RegexOptions.IgnoreCase); + + static string DocumentationRoot + { + get + { + var package = UnityEditor.PackageManager.PackageInfo.FindForAssembly(typeof(AndroidLogcatUtilities).Assembly); + return Path.GetFullPath(Path.Combine(package.resolvedPath, "Documentation~")); + } + } + + static string RelativeToDocumentation(string path) + { + return Path.GetRelativePath(DocumentationRoot, path).Replace('\\', '/'); + } + + static bool IsImage(string path) + { + return kImageExtensions.Contains(Path.GetExtension(path).ToLowerInvariant()); + } + + static IEnumerable<(string markdown, string image)> GetImageReferences() + { + foreach (var markdown in Directory.GetFiles(DocumentationRoot, "*.md", SearchOption.AllDirectories)) + { + var directory = Path.GetDirectoryName(markdown); + foreach (Match match in kImageReference.Matches(File.ReadAllText(markdown))) + { + var path = Uri.UnescapeDataString(match.Groups["path"].Value.Split('#', '?')[0]); + if (path.Contains("://")) + continue; + yield return (RelativeToDocumentation(markdown), RelativeToDocumentation(Path.GetFullPath(Path.Combine(directory, path)))); + } + } + } + + // Compared ordinally: the docs are built and served on case-sensitive file systems, + // so a reference that only differs in case works on Windows but is broken there. + static HashSet GetImageFiles(string folder) + { + return new HashSet( + Directory.GetFiles(folder, "*", SearchOption.AllDirectories).Where(IsImage).Select(RelativeToDocumentation), + StringComparer.Ordinal); + } + + [Test] + public void AllReferencedImagesExist() + { + var images = GetImageFiles(DocumentationRoot); + var missing = GetImageReferences() + .Where(r => !images.Contains(r.image)) + .Select(r => $"{r.markdown} -> {r.image}") + .ToArray(); + + Assert.IsEmpty(missing, "Documentation references images which don't exist:\n" + string.Join("\n", missing)); + } + + [Test] + public void AllImagesAreReferenced() + { + var referenced = new HashSet(GetImageReferences().Select(r => r.image), StringComparer.Ordinal); + var unused = GetImageFiles(Path.Combine(DocumentationRoot, "images")) + .Where(i => !referenced.Contains(i)) + .OrderBy(i => i) + .ToArray(); + + Assert.IsEmpty(unused, "Images not referenced by any documentation page:\n" + string.Join("\n", unused)); + } + + [Test] + public void AllImageNamesAreLowerCase() + { + var invalid = GetImageFiles(DocumentationRoot) + .Where(i => i != i.ToLowerInvariant()) + .OrderBy(i => i) + .ToArray(); + + Assert.IsEmpty(invalid, "Image names must be lower case:\n" + string.Join("\n", invalid)); + } +} diff --git a/com.unity.mobile.android-logcat/Tests/Editor/AndroidLogcatDocumentationTests.cs.meta b/com.unity.mobile.android-logcat/Tests/Editor/AndroidLogcatDocumentationTests.cs.meta new file mode 100644 index 00000000..c2f3d57a --- /dev/null +++ b/com.unity.mobile.android-logcat/Tests/Editor/AndroidLogcatDocumentationTests.cs.meta @@ -0,0 +1,11 @@ +fileFormatVersion: 2 +guid: 6d65280edba04aa4ba328538883264cf +MonoImporter: + externalObjects: {} + serializedVersion: 2 + defaultReferences: [] + executionOrder: 0 + icon: {instanceID: 0} + userData: + assetBundleName: + assetBundleVariant: