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 = "[](" + 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 = "[](" + 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.
+
| **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.
+
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.
## 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 is divided into five sections:
* Keyboard keys
@@ -22,7 +22,7 @@ The inputs window is divided into five sections:
## Keyboard keys
-
+
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
-
+
Includes navigation keys.
## Numpad keys
-
+
Includes numerical keys.
## Miscellaneous keys
-
+
Includes various helper keys for Android:
* Volume keys
@@ -59,18 +59,18 @@ Includes various helper keys for Android:
* Back/Home/Menu
## TV keys
-
+
Incluse basic TV keys.
## Media
-
+
Incluse basic Media keys.
## Send text
- 
+ 
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.
| **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.
+
| **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.
## Memory chart
The memory chart displays the memory allocated for the connected application over time.
- 
+ 
> 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" };
+
+ //  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: