Modernize documentation

.github/workflows/build.yml

@@ -79,6 +79,8 @@ jobs:
         with:
           name: bundles
           path: bundles
+      - name: Build documentation
+        run: npm run docs:build-embed
       - name: Build app
         run: npx electron-builder build --${{ matrix.arch }} --publish never
         env:
@@ -145,6 +147,8 @@ jobs:
         with:
           name: bundles
           path: bundles
+      - name: Build documentation
+        run: npm run docs:build-embed
       - name: Build app
         run: npx electron-builder build --${{ matrix.arch }} --publish never
         env:
@@ -220,6 +224,8 @@ jobs:
         with:
           name: bundles
           path: bundles
+      - name: Build documentation
+        run: npm run docs:build-embed
       - name: Build app
         run: npx electron-builder build --${{ matrix.arch.electronArch }} -l ${{ matrix.format }} --publish never
         env:
@@ -275,6 +281,8 @@ jobs:
         with:
           name: bundles-wpilib
           path: bundles
+      - name: Build documentation
+        run: npm run docs:build-embed
       - name: Build app
         run: npx electron-builder build --publish never --${{ matrix.arch }} -w dir
         env:
@@ -345,6 +353,8 @@ jobs:
         with:
           name: bundles-wpilib
           path: bundles
+      - name: Build documentation
+        run: npm run docs:build-embed
       - name: Build app
         run: npx electron-builder build --publish never --${{ matrix.arch }} -m dir
         env:
@@ -406,6 +416,8 @@ jobs:
         with:
           name: bundles-wpilib
           path: bundles
+      - name: Build documentation
+        run: npm run docs:build-embed
       - name: Build app
         run: npx electron-builder build --publish never --${{ matrix.arch }} -l AppImage
         env:

.github/workflows/publish-docs.yml

@@ -0,0 +1,46 @@
+name: Publish Docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Publish
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          cache: "npm"
+      - name: Install Node.js dependencies
+        run: npm ci
+        env:
+          ASCOPE_NO_FFMPEG: true
+      - name: Build docs
+        run: npm run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "./docsSite/build"
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -6,6 +6,29 @@
 /ThirdPartyLicenses.txt
 /eng.traineddata.gz
 
+### Docs ###
+
+# Dependencies
+/docsSite/node_modules
+
+# Production
+/docsSite/build
+
+# Generated files
+/docsSite/.docusaurus
+/docsSite/.cache-loader
+
+# Misc
+/docsSite/.DS_Store
+/docsSite/.env.local
+/docsSite/.env.development.local
+/docsSite/.env.test.local
+/docsSite/.env.production.local
+
+/docsSite/npm-debug.log*
+/docsSite/yarn-debug.log*
+/docsSite/yarn-error.log*
+
 ### Linux ###
 *~
 

.prettierignore

@@ -1,4 +1,5 @@
 node_modules
 dist
 bundles
-src/licenses.json
+src/licenses.json
+docsSite/build

docsSite/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docsSite/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve("@docusaurus/core/lib/babel/preset")]
+};

docsSite/docs/categories.json

@@ -0,0 +1,14 @@
+{
+  "categories": [
+    {
+      "title": "Introduction",
+      "description": "Learn the basics of our product.",
+      "href": "/docs/introduction"
+    },
+    {
+      "title": "Getting Started",
+      "description": "Start using our product right away.",
+      "href": "/docs/getting-started"
+    }
+  ]
+}

docsSite/docs/getting-started/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Getting Started",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "These pages cover the basics of getting around in AdvantageScope and and accessing data."
+  }
+}

docsSite/docs/getting-started/navigation.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 1
+---
+
+# App Navigation
+
+The screenshot below shows the important elements of the main AdvantageScope window. The exact appearance differs between operating systems.
+
+> Note: To view multiple log files simultaneously, click "File" > "New Window" or press **cmd/ctrl + N**.
+
+![Navigation diagram](./img/navigation-1.png)
+
+## Sidebar
+
+To the left is the sidebar with the list of available tables and fields. Selectable fields are shown in _italics_ and built-in tables (from WPILib or AdvantageKit) are <u>underlined</u>. Click the arrow to expand nested tables. **Drag a single field** to select it or **hold cmd/ctrl** to select a collection of fields by clicking each one. Start dragging the collection of fields to finish the selection.
+
+To search for a field, begin typing in the search box. A dropdown of fields will display, then the selected field will be highlighted in the sidebar and scrolled into view.
+
+> Note: Click and drag on the right edge to resize or hide the sidebar.
+
+![Dragging a field from the sidebar](./img/navigation-2.png)
+
+## Tab Bar
+
+Use the tab bar (blue) to switch between different views. This documentation is available at any time by clicking the 📖 icon to the left. To export the current tab layout (and associated settings), click "File" > "Export Layout..." To import a layout from a file, click "File" > "Import Layout..."
+
+> Note: Tabs can be named to identify their contents. Rename a tab by right-clicking it and selecting "Rename..."
+
+## Navigation Buttons & Playback
+
+The navigation buttons (green) on the top manage the tabs and control playback. The "+" icon adds a new tab (this can be accessed quickly by pressing **cmd/ctrl + T**). The "X" icon closes the selected tab (**cmd/ctrl + W**) and the arrow buttons move the selected tab left or right (**cmd/ctrl + [ OR ]**). Quickly switch between tabs using the arrow keys (**cmd/ctrl + ← OR →**).
+
+![Choosing a tab type](./img/navigation-3.png)
+
+The selected time is synchronized between all tabs, including the line graph, table, field views, and more. Press **←** or **→** to step forward and backward in the log while paused. Playback can be toggled using the play/pause button or by pressing the **space bar**. To adjust the playback speed, **right-click** on the play/pause button.
+
+> Note: Stepping through the log uses a 20ms period by default, and uses the synchronized loop cycle times when viewing an AdvantageKit log.
+
+## Window Pop-Out
+
+It is often useful to view multiple tabs at the same time. Since AdvantageScope synchronizes playback across all tabs, it is possible to perform sophisticated analysis by looking at multiple visualizations at once. An example might be viewing video, field odometry, joystick inputs, and performance graphs all together. Tabs that support pop-out have an additional "Add Window" icon just below the navigation/playback controls.
+
+> Note: When using pop-out windows, playback is controlled from the main AdvantageScope window.
+
+![Creating a pop-out window](./img/navigation-4.png)
+
+## Touch Bar
+
+Navigation is possible using the Touch Bar on supported MacBooks. The slider can be used to scrub through the log, and the "+" button adds a new tab.
+
+![Touch Bar scrubbing interface](./img/navigation-5.png)
+![Touch Bar new tab interface](./img/navigation-6.png)

docsSite/docs/getting-started/open-file.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 2
+---
+
+# Managing Log Files
+
+This section describes how to open log files for analysis.
+
+## Opening a Log
+
+In the menu bar, click "File" > "Open..." or press **cmd/ctrl + O**, then choose a log file from the local disk. Dragging a log file from the system file browser to the AdvantageScope icon or window also causes it to open.
+
+![Opening a saved log](./img/open-file-1.png)
+
+Supported log formats are:
+
+- **WPILOG (.wpilog)** - Produced by WPILib's [built-in data logging](https://docs.wpilib.org/en/stable/docs/software/telemetry/datalog.html) and AdvantageKit v2 (2023) or later. [URCL](../more-features/urcl.md) can be used to capture signals from REV motor controllers to a WPILOG file.
+- **Driver Station logs (.dslog and .dsevents)** - Produced by the [FRC Driver Station](https://docs.wpilib.org/en/stable/docs/software/driverstation/driver-station.html) and saved to "\Users\Public\Documents\FRC\Log Files".
+- **Hoot (.hoot)** - Produced by CTRE's Phoenix 6 [signal logger](https://pro.docs.ctr-electronics.com/en/latest/docs/api-reference/api-usage/signal-logging.html). _Phoenix Tuner X must be installed to open Hoot log files. This feature is only supported on Windows._
+- **RLOG (.rlog)** - Produced by AdvantageKit v1 (2022).
+
+> Note: ".dslog" files include numeric/boolean data and ".dsevents" files include console data. When opening either file type, AdvantageScope searches the same directory for the matching log. For example, when opening "/example/log/file.dslog" AdvantageScope searches for "/example/log/file.dsevents". If found, the fields from both files are combined.
+
+## Merging Logs
+
+Log files can be merged automatically. Possible use cases include:
+
+- Merging DS log data with WPILOG data from the robot.
+- Merging WPILOG data from different matches to compare data.
+
+Click "File" > "Open Multple..." or press **shift + cmd/ctrl + O**, then choose up to 10 log files from the local disk. The fields from each log will be recorded under tables named "Log0", "Log1", etc. The timestamps of each log are adjusted such the robot is first enabled at 0 seconds (negative timestamps are permitted).
+
+## Downloading from a roboRIO
+
+Open the preferences window by pressing **cmd/ctrl + comma** or clicking "Help" > "Show Preferences..." (Windows/Linux) or "AdvantageScope" > "Settings..." (macOS). Update the "roboRIO Address" and "roboRIO Log Folder".
+
+> Note: Click "File" > "Use USB roboRIO Address" to temporarily use the IP address "172.22.11.2" for all connections.
+
+![Diagram of roboRIO preferences](./img/open-file-2.png)
+
+Click "File" > "Download Logs..." or press **cmd/ctrl + D** to open the download window. Once connected to the roboRIO, available logs are shown with the newest at the top. Select one or more log files to download (shift-click to select a range or **cmd/ctrl + A** to select all). Then click the ↓ symbol and select a save location.
+
+> Note: When downloading multiple files, AdvantageScope skips any that are already found in the destination folder.
+
+![Downloading log files](./img/open-file-3.png)

docsSite/docs/getting-started/open-live.md

@@ -0,0 +1,68 @@
+---
+sidebar_position: 2
+---
+
+# Connecting to Live Sources
+
+All visualizations in AdvantageScope are designed to receive live data from a robot or simulator in addition to log files. This section describes how to connect to real time data sources.
+
+## Configuration
+
+Open the preferences window by pressing **cmd/ctrl + comma** or clicking "Help" > "Show Preferences..." (Windows/Linux) or "AdvantageScope" > "Settings..." (macOS).
+
+![Diagram of live preferences](./img/open-live-1.png)
+
+### roboRIO Address
+
+Enter the roboRIO address using a 10.TE.AM.2 IP address as described in the [WPILib docs](https://docs.wpilib.org/en/stable/docs/networking/networking-introduction/ip-configurations.html#te-am-ip-notation). Click "File" > "Use USB roboRIO Address" to temporarily use the IP address "172.22.11.2" for all connections.
+
+### Live Source
+
+The following sources of live data are supported by AdvantageScope:
+
+- **NetworkTables 4:** This is the default networking protocol starting in WPILib 2023, and is commonly used by dashboards, coprocessors, etc. See the [WPILib documentation](https://docs.wpilib.org/en/stable/docs/software/networktables/index.html) for more details. Note that NetworkTables 3 (used by WPILib 2022 and older) is not supported by AdvantageScope.
+- **NetworkTables 4 (AdvantageKit):** This mode is designed for use with robot code running AdvantageKit, which publishes to the "/AdvantageKit" table in NetworkTables. The only difference from the **NetworkTables 4** mode is that the "/AdvantageKit" table is used as the root, which allows for easier switching between an NT4 connection and an AdvantageKit log file.
+- **Phoenix Diagnostics:** This mode uses HTTP to connect to a Phoenix [diagnostic server](https://pro.docs.ctr-electronics.com/en/latest/docs/installation/running-diagnostics.html), which allows for data streaming from CTRE CAN devices with [Phoenix 6](https://pro.docs.ctr-electronics.com/en/latest/). This is similar to the [plotting feature](https://pro.docs.ctr-electronics.com/en/latest/docs/tuner/plotting.html) in Phoenix Tuner, but includes support for previewing values in the sidebar and storing the full history of signals (like any other AdvantageScope live source). Note that the diagnostic server only supports plotting signals from **one device at a time**. AdvantageScope will switch between devices automatically based on the signals being viewed.
+- **PathPlanner 2023:** This mode connects using the `PathPlannerServer` protocol used for telemetry by PathPlanner 2023. The connection is always initiated on port 5811. Note that PathPlanner 2024 and later publish telemetry data using NetworkTables, so the **NetworkTables 4** mode should be used.
+- **RLOG Server:** This protocol is supported by AdvantageKit as an alternative to NetworkTables. The connection is initiated on port 5800 by default.
+
+> Note: The Phoenix Diagnostics live mode uses an undocumented protocol that may be changed in future Phoenix updates. If this mode does not function properly, please update to the latest version of AdvantageScope. If the issue persists, please [open an issue](https://github.com/Mechanical-Advantage/AdvantageScope/issues) to let us know.
+
+### Live Mode
+
+When NetworkTables is used as the live source, the following live modes can be selected:
+
+- **Low Bandwidth (Default):** AdvantageScope only requests data from the server for fields that are actively being used. Data published before a field was selected will not be available. This mode is **highly recommended** when running in an environment with limited network bandwidth, such as on the field.
+- **Logging:** AdvantageScope requests data for all fields regardless of whether they are actively being used. This means that fields can be viewed retroactively by pausing the stream of live data (see below). This mode is often useful during development but **should NOT be used on the field**.
+
+### Discard Live Data
+
+During a live connection, data is stored locally to allow for replay of past data (see "Viewing Live Data" below). To avoid very high memory usage, data is discarded after 20 minutes by default. A shorter period can be selected to reduce memory usage, or "Never" can be selected to store live data indefinitely.
+
+## Starting the Connection
+
+To start the connection to a robot (using the configured "roboRIO Address") or a simulator (using "127.0.0.1"), follow these steps:
+
+- **Robot:** Click "File" > "Connect to Robot" or press **cmd/ctrl + K**
+- **Simulator:** Click "File" > "Connect to Simulator" or press **shift + cmd/ctrl + K**
+
+The window title displays the IP address and the text "Searching" until the robot/sim is connected. It attempts to reconnect automatically using the same settings after a disconnect.
+
+## Viewing Live Data
+
+When connected to a live source, AdvantageScope locks all tabs to the current time by default. Views like the 📉 [Line Graph](../tab-reference/line-graph.md) and 🔢 [Table](../tab-reference/table.md) autoscroll, and views like odometry and joysticks display the current values of each field. Clicking the red arrow button in the navigation bar toggles this lock, enabling viewing and replay of past data.
+
+> Note: Scrolling to the left in the line graph also unlocks from the current time, and scrolling all the way to the right locks to the current time again.
+
+![Live lock/unlock button](./img/open-live-2.png)
+
+## Tuning Mode
+
+Some live sources support live tuning of numeric and boolean values. For example, this feature can be used to [tune controller gains](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/introduction/tutorial-intro.html) when connected to a NetworkTables source. Note that the robot code must support receiving gains via NetworkTables.
+
+By default, all values in AdvantageScope are read-only. To toggle tuning mode, **click the slider icon** to the right of the search bar when connected to a supported live source. When the icon is purple, tuning mode is active and field editing is enabled.
+
+- To edit a **numeric field**, enter a new value using the text box to the right of the field in the sidebar. The value is published after the input is deselected or the "Enter" key is pressed. Leave the text box blank to use the robot-published value.
+- To toggle a **boolean field**, click the red or green circle to the right of the field in the sidebar.
+
+> Note: This feature is not intended for controlling the robot on the field. Support for dashboard-style inputs like choosers, trigger buttons, etc. will not be added.