Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .github/workflows/prefill-pr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
32 changes: 32 additions & 0 deletions .yamato/docs.yml
Original file line number Diff line number Diff line change
@@ -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")
10 changes: 10 additions & 0 deletions .yamato/docs/preview-docs.bat
Original file line number Diff line number Diff line change
@@ -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
13 changes: 13 additions & 0 deletions .yamato/docs/preview-docs.sh
Original file line number Diff line number Diff line change
@@ -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
15 changes: 15 additions & 0 deletions .yamato/docs/write-index.bat
Original file line number Diff line number Diff line change
@@ -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 ^<!doctype html^>
echo ^<meta charset="utf-8"^>
echo ^<meta http-equiv="refresh" content="0; url=%TARGET%"^>
echo ^<title^>%DOCS% documentation^</title^>
echo ^<a href="%TARGET%"^>Open the %DOCS% documentation^</a^>
) > ..\index.html
echo Wrote docs~\index.html pointing at %TARGET%
Original file line number Diff line number Diff line change
Expand Up @@ -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 <package_name> kill -s <posix_signal> <process_id>**. For more information, refer to [standard signals](https://man7.org/linux/man-pages/man7/signal.7.html).<br><br>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). |
Expand All @@ -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 <process_id> <trim_level>**. 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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
16 changes: 8 additions & 8 deletions com.unity.mobile.android-logcat/Documentation~/inputs-window.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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** |
Expand All @@ -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.<br/> **Note**: This metric is only visible on Android 11 or higher. |
Expand All @@ -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.
Original file line number Diff line number Diff line change
@@ -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 <img src="path">
static readonly Regex kImageReference = new Regex(
@"!\[[^\]]*\]\(\s*<?(?<path>[^)\s>]+)>?(?:\s+""[^""]*"")?\s*\)|<img\s[^>]*src\s*=\s*[""'](?<path>[^""']+)[""']",
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<string> GetImageFiles(string folder)
{
return new HashSet<string>(
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<string>(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));
}
}

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.