Update docs

ShortestPathLab · May 8, 2024 · 9b55243 · 9b55243
1 parent f03bd74
commit 9b55243
Show file tree

Hide file tree

Showing 41 changed files with 226 additions and 43 deletions.
diff --git a/blog/2023-09-22-changelog/index.md b/blog/2023-09-22-changelog/index.md
@@ -11,7 +11,7 @@ tags: [changelog, v1.0.4]
 
 #### UI Overhaul
 
-Waypoint is completely rebuilt to support dynamic and reconfigurable panels, so you can adjust the UI to fit your workflow or use case. Check out the [use cases](#use-cases) section for examples.
+Waypoint is completely rebuilt to support dynamic and reconfigurable panels, so you can adjust the UI to fit your workflow or use case. Check out the use cases section for examples.
 
 ![aux-1](./assets/22-09-2023/aux-1.png)
 
@@ -96,7 +96,7 @@ The renderer and map parser performs optimisations to handle the rendering of la
 
 [Click here for full size](./assets/22-09-2023/large-map-florida.mkv)
 
-### Use Cases <a id="use-cases"></a>
+### Use Cases
 
 #### Visualising a Search Trace
 

diff --git a/docs/1-overview.md b/docs/1-overview.md
@@ -10,11 +10,11 @@ sidebar_position: 1
 
 It's easy to get started.
 
-1. Print logs as [search traces](./3-search-trace)
-2. Load those into the [Posthoc visualiser](./2-visualiser)
+1. Print logs as [search traces](./search-trace)
+2. Load those into the [Posthoc visualiser](./visualiser/overview)
 3. Voila!
 
-[Search trace](./3-search-trace) is log-like YAML format that describes what happened during your algorithm, and how you want to visualise it. If you're generating logs already, we invite you to convert them to search traces. Then, [Posthoc](./2-visualiser) is a comprehensive, no-install visualiser that helps you interpret and analyse search traces.
+[Search trace](./search-trace) is log-like YAML format that describes what happened during your algorithm, and how you want to visualise it. If you're generating logs already, we invite you to convert them to search traces. Then, [Posthoc](./visualiser/overview) is a comprehensive, no-install visualiser that helps you interpret and analyse search traces.
 
 ## Find and fix problems
 
@@ -67,9 +67,3 @@ Building visualisations is a lot of effort; we want to focus on writing and perf
 Posthoc adds visualisation to our problem-solving toolkit 🛠️.
 
 When problems occur in a spatial environment &mdash; navigating through roads, corridors, terrain etc &mdash; it's just natural to reason about them visually. Posthoc lets us create quick-and-dirty visualisations to leverage intuition, debug problems, draw insights, and collaborate with each other.
-
-:::warning
-
-This site is under construction. Content may be inaccurate or missing.
-
-:::
diff --git a/docs/2-search-trace.md b/docs/2-search-trace.md
@@ -102,7 +102,7 @@ Custom views get you quickly going to creating something useful, but its also a
 
 ![Complex view](complex-view.png)
 
-See the [2D renderer API reference](category/renderer) for a list of primitives provided by the built-in renderer.
+See the [**Pixel** API reference](./visualiser/pixel-renderer#api) for a list of primitives provided by the built-in renderer.
 
 ## Nested views
 
@@ -161,10 +161,16 @@ events:
 
 If a property is a single expression, the property's value and type is taken from the result of the expression. But, if the property contains multiple expressions, or if there's text around the expressions, it becomes a concatenated string instead.
 
-See the [search trace API reference](api/search-trace) for a list of properties available in expressions.
+See the [search trace API reference](./search-trace#api) for a list of properties available in expressions.
 
 ## Special properties
 
+### `type`
+
+The `type` property doesn't do anything, but it's used to drive some parts of **Posthoc**'s UI.
+
+![Alt text](image-2.png)
+
 ### `clear`
 
 Control when elements should be cleared.
@@ -278,8 +284,75 @@ events:
 
 ## API
 
-The search trace API defines how you can write and structure your search trace. [See the search trace API](api/search-trace).
+### Definition
+
+#### `Trace`
+
+The root of a search trace file.
+
+```ts
+type Trace = {
+  version: string;
+  views?: Dictionary<View[]>;
+  pivot?: Pivot;
+  events?: Event[];
+};
+```
+
+#### `View`
+
+A primitive or higher-order view.
+
+```ts
+type View = {
+  $: string;
+  [K in string]?: Property<any>;
+  clear?: Property<boolean | string>;
+  $info?: Dictionary<Property<any>>;
+  $if?: Property<boolean>;
+  $for?: {
+    $let?: string;
+    $from?: Property<number>;
+    $to?: Property<number>;
+    $to?: Property<number>;
+  };
+};
+```
+
+#### `Property`
+
+```ts
+type Property<T> = T | PropertyExpression<T>;
+```
+
+Where `PropertyExpression<T>` is a [property expression](#property-expressions) that evaluates to type T.
+
+#### `Pivot`
+
+Define the center-point of an event.
+
+```ts
+type Pivot = {
+  scale?: Property<number>;
+  x?: Property<number>;
+  y?: Property<number>;
+  z?: Property<number>;
+  w?: Property<number>;
+};
+```
+
+#### `Event`
+
+A recorded event.
+
+```ts
+type Event = Dictionary<any>;
+```
+
+### Primitives
+
+The search trace format itself doesn't define any primitives. Renderers do. For the built-in renderer, **Pixel**, see the [**Pixel** primitives here](visualiser/pixel-renderer#primitives).
 
-The renderer specifies what primitives are available and how you can use them. For the built-in renderer, see the [2D renderer API here](category/renderer).
+### YAML
 
-Check out the [YAML 1.2.2 documentation](https://yaml.org/spec/1.2.2/) for all the ways you can write YAML.
+The search trace is a YAML document. Check out the [YAML 1.2.2 documentation](https://yaml.org/spec/1.2.2/) for all the ways you can write YAML.
diff --git a/docs/3-visualiser/3-1-user-guide/_category_.json b/docs/3-visualiser/3-1-user-guide/_category_.json
@@ -1,5 +1,5 @@
 {
-  "label": "User Guide",
+  "label": "User guide",
   "position": 3,
   "collapsed": true,
   "link": {

diff --git a/docs/3-visualiser/3-1-user-guide/extensions.md b/docs/3-visualiser/3-1-user-guide/extensions.md
@@ -1,12 +1,12 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # Extensions
 
 ## Adapters
 
-Adapters implement the [visualiser adapter protocol](.) to connect solvers to Posthoc.
+Adapters implement the [Visualiser Adapter Protocol](/docs/visualiser-adapter-protocol) to connect solvers to Posthoc.
 
 ### Built-in adapters
 

diff --git a/docs/3-visualiser/3-1-user-guide/interface.md b/docs/3-visualiser/3-1-user-guide/interface.md
@@ -15,7 +15,7 @@ Explore Posthoc and its community creations via examples and guides.
 ## Layers
 
 Add, edit, and remove layers. The options available to a layer depends on the layer type.
-[Read more about layers here.](.)
+[Read more about layers here.](./layers)
 
 ![Screenshot of layer](interface-views-layers-layer.png)
 
@@ -29,15 +29,15 @@ Add, edit, and remove layers. The options available to a layer depends on the la
 
 ### Trace options
 
-Load a [search trace](.) file.
+Load a [search trace](./layers#trace) file.
 
 | Name   | Description                                     |
 | ------ | ----------------------------------------------- |
 | Source | The search trace that gets drawn on this layer. |
 
 ### Map options
 
-Load a [map](.).
+Load a [map](./layers#map).
 
 | Name                | Description                                           |
 | ------------------- | ----------------------------------------------------- |
@@ -46,7 +46,7 @@ Load a [map](.).
 
 ### Query options
 
-Make a query using the [visualiser adapter protocol](.).
+Make a query using the [Visualiser Adapter Protocol](/docs/visualiser-adapter-protocol).
 
 | Name | Description                            |
 | ---- | -------------------------------------- |
@@ -71,10 +71,10 @@ Browse the events of a search trace.
 
 ### Toolbar items
 
-| Name     | Description                                          | Default             |
-| -------- | ---------------------------------------------------- | ------------------- |
-| Layers   | The layers to render.                                | Render all layers.  |
-| Renderer | The renderer to use. [Read more about renderers.](.) | Pick automatically. |
+| Name     | Description                                                               | Default             |
+| -------- | ------------------------------------------------------------------------- | ------------------- |
+| Layers   | The layers to render.                                                     | Render all layers.  |
+| Renderer | The renderer to use. [Read more about renderers.](./extensions#renderers) | Pick automatically. |
 
 ## Graph
 
@@ -161,7 +161,7 @@ Configure Posthoc.
 
 ### Extensions
 
-Manage connected solvers, adapters, renderers, and map parsers. [Read more about extensions here.](.)
+Manage connected solvers, adapters, renderers, and map parsers. [Read more about extensions here.](./extensions)
 
 ## Customising views
 
@@ -195,11 +195,11 @@ The titlebar gives you commands that control Posthoc as a whole.
 
 ![Alt text](interface-titlebar-workspace-export-workspace.png)
 
-| Item             | Description                                                                                                     |
-| ---------------- | --------------------------------------------------------------------------------------------------------------- |
-| Open workspace   | Select a \*.workspace file to load.                                                                             |
-| Add panel below  | Save the current project as a \*.workspace file.                                                                |
-| Export workspace | Save the current project as a _.workspace and _.workspace.meta file. [Read more about exporting workspaces.](.) |
+| Item             | Description                                                          |
+| ---------------- | -------------------------------------------------------------------- |
+| Open workspace   | Select a \*.workspace file to load.                                  |
+| Add panel below  | Save the current project as a \*.workspace file.                     |
+| Export workspace | Save the current project as a _.workspace and _.workspace.meta file. |
 
 ## Sidebar
 

diff --git a/docs/3-visualiser/3-1-user-guide/layers.md b/docs/3-visualiser/3-1-user-guide/layers.md
@@ -36,7 +36,7 @@ It's optional to use maps because you might not be doing pathfinding search. We
 
 ### Query
 
-Query layers interact with extensions that implement the [visualiser adapter protocol](.). The query layer and the visualiser adapter protocol should allow you to interactively call your solver, complete with custom parameters and inputs.
+Query layers interact with extensions that implement the [Visualiser Adapter Protocol](/docs/visualiser-adapter-protocol). The query layer and the Visualiser Adapter Protocol should allow you to interactively call your solver, complete with custom parameters and inputs.
 
 ![Alt text](image-5.png)
 

diff --git a/docs/3-visualiser/contributing.md b/docs/3-visualiser/contributing.md
@@ -3,3 +3,7 @@ sidebar_position: 4
 ---
 
 # Contributing
+
+We welcome new issues, discussions, and PRs on our [Github repository](https://github.com/path-visualiser/app).
+
+Check out our roadmap [here](https://github.com/orgs/path-visualiser/projects/2/views/2).
diff --git a/docs/3-visualiser/image-1.png b/docs/3-visualiser/image-1.png
diff --git a/docs/3-visualiser/image-6.png b/docs/3-visualiser/image-6.png
diff --git a/docs/3-visualiser/image-7.png b/docs/3-visualiser/image-7.png
diff --git a/docs/3-visualiser/overview.md b/docs/3-visualiser/overview.md
@@ -4,7 +4,7 @@ sidebar_position: 2
 
 # Overview
 
-Posthoc visualises [search traces](./search-trace). It gives you a variety of tools to help you analyse and debug your algorithm. It's quick to get started and install-free &mdash; even better, it's robust and performant enough to support the largest of problem instances.
+Posthoc visualises [search traces](/docs/search-trace). It gives you a variety of tools to help you analyse and debug your algorithm. It's quick to get started and install-free &mdash; even better, it's robust and performant enough to support the largest of problem instances.
 
 ![Complex view](../complex-view.png)
 
@@ -18,7 +18,9 @@ You can use Posthoc directly in a browser.
 
 ### Posthoc PWA
 
-Optionally, you can [install Posthoc as a web app](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Installing) so that it runs in its own window.
+Optionally, you can [install Posthoc as a web app](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Guides/Installing) so that it runs in its own window. You can also install the Posthoc PWA on mobile devices.
+
+![Alt text](image-1.png)
 
 ### Standalone builds