From 3be60362ab373e233391d70585b8090835eab15b Mon Sep 17 00:00:00 2001 From: Eli Pinkerton Date: Fri, 9 Oct 2026 20:30:34 +0000 Subject: [PATCH] Add the docs-site troubleshooting page The site documented the window's happy paths; the behaviors that look like bugs but are designed (async loading, search index build, refresh deferral while Unity is busy, minimum window and pane sizes, corrupt state recovery) and the capture pipeline's regeneration flow lived only in issues and progress notes. The roadmap's T11 item asked for a troubleshooting page. Refs #114. ## Behavior - docs/troubleshooting.md covers the recorded topics, each traced to main: the Loading... counter and Loading In Progress refusal, Building search index..., busy-database refresh deferral and postprocessor auto-refresh, missing-script and exact-type listing rules, idle-time selection normalization, 860x480 / pane minimums with preferred-vs-clamped sizes, user-state and settings-asset recovery, and capture regeneration (CLI, output-dir argument and env var, project-root path resolution, meta-free dot-folder staging, the macOS 6000.4 render-gap limit, container workflow). - mkdocs.yml nav gains Troubleshooting after Extending; the index page links it in Where to go next. ## Validation - mkdocs build --strict green; site/troubleshooting/ published with all ten sections, the five PNGs present, and zero .meta files. - npm run lint:llm green; npm pack payload unchanged (172 files). --- docs/index.md | 2 + docs/troubleshooting.md | 154 +++++++++++++++++++++++++++++++++++ docs/troubleshooting.md.meta | 7 ++ mkdocs.yml | 2 + 4 files changed, 165 insertions(+) create mode 100644 docs/troubleshooting.md create mode 100644 docs/troubleshooting.md.meta diff --git a/docs/index.md b/docs/index.md index 384c0e1..8f47b08 100644 --- a/docs/index.md +++ b/docs/index.md @@ -52,6 +52,8 @@ Open the window with **Tools → Wallstop Studios → Data Visualizer**. - [Managing assets](managing-assets.md) — create, clone, rename, move, delete, and run processors. - [Organizing your data](organizing.md) — ordering, layout, themes, persistence, and Play Mode. - [Extending the window](extending.md) — attributes, `BaseDataObject`, processors, and custom inspector content. +- [Troubleshooting](troubleshooting.md) — slow loading, stale views, missing assets, window size limits, and capture regeneration. +- [Troubleshooting](troubleshooting.md) — what slow loading, stale views, missing assets, and small windows mean, plus the capture pipeline's limits. - [README](https://github.com/wallstop/DataVisualizer#readme) — the repository README, which links the video walkthrough. - [Video walkthrough](https://youtu.be/3oUxUSKNyhw) — a visual tour of the window. - [Issues](https://github.com/wallstop/DataVisualizer/issues) — known problems and feature requests. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..5cab30a --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,154 @@ +# Troubleshooting + +This page lists behaviors that can look like a bug but are the window working +as designed, and what to do when something genuinely is wrong. Each section +links to the page that documents the feature in full. + +## The object list fills in gradually + +Selecting a type loads its instances asynchronously, so the list can still be +filling while you work. The header row shows an italic `Loading... (n/total)` +counter until the load finishes. + +- Assets whose script is missing, or whose type does not exactly match the + selected type, are skipped and do not count toward the total, so the counter + reaches its end instead of stalling. +- Running a processor while the selected type is still loading is refused with + a **Loading In Progress** dialog, because it would touch only the subset that + has arrived. Wait for the counter to disappear. See + [Refusal while loading](managing-assets.md#refusal-while-loading). +- A list that never finishes loading usually means the console holds script + compile errors. Fix those first; the window reads only assets Unity can + resolve. + +## Search says "Building search index…" + +The first search after the window opens may show **Building search index…** +while the background index loads. The popover stays open with your query, and +the search re-runs automatically when the index is ready — no action needed. +See [Global search](search-and-filter.md#global-search). + +## The window does not update after an asset change + +While Unity reports the AssetDatabase busy — a script compile or a running +import — the window defers work that would force asset type resolution. The +deferred work happens once the database idles; nothing is lost. + +The window refreshes itself when a tracked `.asset` file is imported, moved, +or deleted, and a theme change to the applied theme applies immediately. If a +view looks stale after such a change, check the console for errors from other +packages first: an exception in another import handler can stop Unity's +broadcast chain. + +While the editor is playing, package-driven work pauses entirely and refresh +requests are remembered until you leave Play Mode. See +[While the editor is playing](organizing.md#while-the-editor-is-playing). + +## An asset is missing from the list + +- The object list shows only assets whose exact type matches the selected row. + An asset of a subclass appears when that subclass is selected, not under the + base type. +- An asset whose script no longer compiles or whose script GUID is broken + resolves to no type at all and is skipped. Unity flags such assets as + *Missing (Mono Script)* in the Inspector; fixing the script restores the + asset in the list. +- A type whose assembly failed to compile disappears from the catalog until + the code compiles again. Tracked types and your ordering survive; nothing on + disk changes. +- Removing a type from the catalog never deletes assets. See + [Removing a type from the catalog](extending.md#removing-a-type-from-the-catalog). + +## The selection resets itself + +The saved selection for a type is verified against the AssetDatabase. Right +after a recompile or import, verification would be unreliable and could log +Unity's missing-script warning for every unresolved asset, so the window waits +until the database idles and then keeps selections that are still valid and +clears only genuinely invalid ones — typically an asset whose script is gone. +If your selection drops after a recompile, the underlying asset usually failed +to resolve; check the console. + +## The window will not shrink below a certain size + +The window enforces a minimum of 860x480 pixels, and each pane enforces its own +minimum width: 320 px for namespaces, 220 px for the object list, and 260 px +for the inspector. Layout below a pane minimum is refused rather than persisted, +so shrinking and growing the window back does not corrupt your saved widths. + +When the operating system cannot honor the minimum — a small monitor or a tight +side-docked placement — the window clamps to the available space and treats +that as temporary: your preferred size is kept separately and restored when the +space returns. See [Pane widths](organizing.md#pane-widths). + +## The arrangement did not load + +State lives in one of two places, chosen by **Persist State in UserState**: + +- User state: `DataVisualizerUserState.json` in Unity's per-user persistent + data path. Each developer has a private copy. +- Project asset: a `DataVisualizerSettings` asset, created at + `Assets/Editor/DataVisualizerSettings.asset` on first use if none exists. + +If the stored state is empty or corrupt, the window logs a warning or error, +starts with default state, and keeps going — it never half-applies broken +state. To recover your arrangement, restore the file or asset from backup or +let the window rebuild it; switching between the two stores copies the current +state across. See [Persistence](organizing.md#persistence). + +The pane widths and the Data Folder are not part of that state; they stay with +the settings asset or editor preferences as described on the +[Organizing](organizing.md) page. + +## Recreating the documentation images + +The five images in `docs/images/` are generated from the live window, not +hand-taken. The capture driver lives at `Tests/Editor/DocsImageCapture.cs` and +arranges a known window state before each shot. + +Regenerate all shots with a batch-mode Unity invocation: + +```sh +unity -projectPath -batchmode -quit -executeMethod \ + WallstopStudios.DataVisualizer.Tests.Editor.DocsImageCapture.RunFromCommandLine \ + -docsImageOutputDir +``` + +- The output directory also comes from the `DATAVISUALIZER_DOCS_IMAGE_DIR` + environment variable; without either, shots land in the project's + `Temp/DocsImageCaptures`. The driver never writes into `docs/` by default; + review results before committing them. +- Relative output paths resolve against the Unity **project root**, not the + package folder. To stage shots under the package, pass an absolute path to a + dot-folder such as `.docs-captures/` — Unity generates no `.meta` files for + dot-folders, so the staging area stays out of the importer. +- Each capture is validated against the laid-out window: regions Unity's + offscreen renderer should have painted are measured in the PNG, and a capture + that omits them fails closed instead of saving a misleading image. + +Known capture limit, recorded on +[#114](https://github.com/wallstop/DataVisualizer/issues/114): Unity's +offscreen panel renderer on macOS 6000.4 omitted several inspector and list +subtrees (the same window paints them fully on screen and on Windows 6000.5). +The driver detects that host gap and fails closed rather than publishing +blanked imagery; every committed PNG was produced and pixel-verified on +Windows 6000.5. + +## Working from a container + +When the package checkout is edited inside a container while Unity runs on the +host, the host picks up container-side edits through the mounted folder and +recompiles on focus. Do not edit files while a test suite or capture run is in +progress on the host: the host watcher racing a mid-run edit can fail the run +with unrelated errors. Let the host finish, recompile, and report up to date +before the next edit, then re-run. + +## Still stuck + +- [Getting started](getting-started.md) — the first-session walkthrough. +- [Search and filtering](search-and-filter.md) — what each finder matches. +- [Managing assets](managing-assets.md) — asset operations and processors. +- [Organizing your data](organizing.md) — layout, themes, persistence. +- [Issues](https://github.com/wallstop/DataVisualizer/issues) — known problems + and where to report new ones. Data Visualizer is alpha software; a report + with the console output and Unity version helps a lot. diff --git a/docs/troubleshooting.md.meta b/docs/troubleshooting.md.meta new file mode 100644 index 0000000..17fcdce --- /dev/null +++ b/docs/troubleshooting.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 6a0b1404c22f4e93aa6f071b7c73205d +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/mkdocs.yml b/mkdocs.yml index cc25879..56c4c98 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -48,6 +48,8 @@ nav: - Managing assets: managing-assets.md - Organizing your data: organizing.md - Extending the window: extending.md + - Troubleshooting: troubleshooting.md + - Troubleshooting: troubleshooting.md validation: nav: