[docs] Create quick-start guide (PhotonVision#1528)

Add a quick-start guide to help answer more questions with fewer words.
---------

Co-authored-by: Matt M <[email protected]>

docs/source/conf.py

@@ -120,6 +120,18 @@ def setup(app):
         "color-api-overall": "#101010",
         "color-inline-code-background": "#0d0d0d",
     },
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/photonvision/photonvision",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
 }
 
 suppress_warnings = ["epub.unknown_project_files"]

docs/source/docs/additional-resources/config.md

@@ -1,6 +1,6 @@
 # Filesystem Directory
 
-PhotonVision stores and loads settings in the {code}`photonvision_config` directory, in the same folder as the PhotonVision JAR is stored. On the Pi image as well as the Gloworm, this is in the {code}`/opt/photonvision` directory. The contents of this directory can be exported as a zip archive from the settings page of the interface, under "export settings". This export will contain everything detailed below. These settings can later be uploaded using "import settings", to restore configurations from previous backups.
+PhotonVision stores and loads settings in the {code}`photonvision_config` directory, in the same folder as the PhotonVision JAR is stored. On supported hardware, this is in the {code}`/opt/photonvision` directory. The contents of this directory can be exported as a zip archive from the settings page of the interface, under "export settings". This export will contain everything detailed below. These settings can later be uploaded using "import settings", to restore configurations from previous backups.
 
 ## Directory Structure
 
@@ -12,20 +12,20 @@ The directory structure is outlined below.
 ```
 
 - calibImgs
-    - Images saved from the last run of the calibration routine
+  - Images saved from the last run of the calibration routine
 - cameras
-    - Contains a subfolder for each camera. This folder contains the following files:
-        - pipelines folder, which contains a {code}`json` file for each user-created pipeline.
-        - config.json, which contains all camera-specific configuration. This includes FOV, pitch, current pipeline index, and calibration data
-        - drivermode.json, which contains settings for the driver mode pipeline
+  - Contains a subfolder for each camera. This folder contains the following files:
+    - pipelines folder, which contains a {code}`json` file for each user-created pipeline.
+    - config.json, which contains all camera-specific configuration. This includes FOV, pitch, current pipeline index, and calibration data
+    - drivermode.json, which contains settings for the driver mode pipeline
 - imgSaves
-    - Contains images saved with the input/output save commands.
+  - Contains images saved with the input/output save commands.
 - logs
-    - Contains timestamped logs in the format {code}`photonvision-YYYY-MM-D_HH-MM-SS.log`. Note that on Pi or Gloworm these timestamps will likely be significantly behind the real time.
+  - Contains timestamped logs in the format {code}`photonvision-YYYY-MM-D_HH-MM-SS.log`. These timestamps will likely be significantly behind the real time. Coprocessors on the robot have no way to get current time.
 - hardwareSettings.json
-    - Contains hardware settings. Currently this includes only the LED brightness.
+  - Contains hardware settings. Currently this includes only the LED brightness.
 - networkSettings.json
-    - Contains network settings, including team number (or remote network tables address), static/dynamic settings, and hostname.
+  - Contains network settings, including team number (or remote network tables address), static/dynamic settings, and hostname.
 
 ## Importing and Exporting Settings
 
@@ -41,10 +41,10 @@ The entire settings directory can be exported as a ZIP archive from the settings
 A variety of files can be imported back into PhotonVision:
 
 - ZIP Archive ({code}`.zip`)
-    - Useful for restoring a full configuration from a different PhotonVision instance.
+  - Useful for restoring a full configuration from a different PhotonVision instance.
 - Single Config File
-    - Currently-supported Files
-        - {code}`hardwareConfig.json`
-        - {code}`hardwareSettings.json`
-        - {code}`networkSettings.json`
-    - Useful for simple hardware or network configuration tasks without overwriting all settings.
+  - Currently-supported Files
+    - {code}`hardwareConfig.json`
+    - {code}`hardwareSettings.json`
+    - {code}`networkSettings.json`
+  - Useful for simple hardware or network configuration tasks without overwriting all settings.

docs/source/docs/installation/index.md → docs/source/docs/advanced-installation/index.md

@@ -1,6 +1,6 @@
-# Installation & Setup
+# Advanced Installation
 
-This page will help you install PhotonVision on your coprocessor, wire it, and properly setup the networking in order to start tracking targets.
+This page will help you install PhotonVision on non-supported coprocessor.
 
 ## Step 1: Software Install
 
@@ -14,25 +14,5 @@ You only need to install PhotonVision on the coprocessor/device that is being us
 :maxdepth: 3
 
 sw_install/index
-updating
-```
-
-## Step 2: Wiring
-
-This section will walk you through how to wire your coprocessor to get power.
-
-```{toctree}
-:maxdepth: 1
-
-wiring
-```
-
-## Step 3: Networking
-
-This section will walk you though how to connect your coprocessor to a network. This section is very important (and easy to get wrong), so we recommend you read it thoroughly.
-
-```{toctree}
-:maxdepth: 1
-
-networking
+prerelease-software
 ```

docs/source/docs/advanced-installation/prerelease-software.md

@@ -0,0 +1,23 @@
+# Installing Pre-Release Versions
+
+Pre-release/development version of PhotonVision can be tested by installing/downloading artifacts from Github Actions (see below), which are built automatically on commits to open pull requests and to PhotonVision's `master` branch, or by {ref}`compiling PhotonVision locally <docs/contributing/building-photon:Build Instructions>`.
+
+:::{warning}
+If testing a pre-release version of PhotonVision with a robot, PhotonLib must be updated to match the version downloaded! If not, packet schema definitions may not match and unexpected things will occur. To update PhotonLib, refer to {ref}`installing specific version of PhotonLib<docs/programming/photonlib/adding-vendordep:Install Specific Version - Java/C++>`.
+:::
+
+GitHub Actions builds pre-release version of PhotonVision automatically on PRs and on each commit merged to master. To test a particular commit to master, navigate to the [PhotonVision commit list](https://github.com/PhotonVision/photonvision/commits/master/) and click on the check mark (below). Scroll to "Build / Build fat JAR - PLATFORM", click details, and then summary. From here, JAR and image files can be downloaded to be flashed or uploaded using "Offline Update".
+
+```{image} images/gh_actions_1.png
+:alt: Github Actions Badge
+```
+
+```{image} images/gh_actions_2.png
+:alt: Github Actions artifact list
+```
+
+Built JAR files (but not image files) can also be downloaded from PRs before they are merged. Navigate to the PR in GitHub, and select Checks at the top. Click on "Build" to display the same artifact list as above.
+
+```{image} images/gh_actions_3.png
+:alt: Github Actions artifacts from PR
+```

docs/source/docs/installation/sw_install/index.md → docs/source/docs/advanced-installation/sw_install/index.md

@@ -1,16 +1,5 @@
 # Software Installation
 
-## Supported Coprocessors
-
-```{toctree}
-:maxdepth: 1
-
-raspberry-pi
-limelight
-orange-pi
-snakeyes
-```
-
 ## Desktop Environments
 
 ```{toctree}
@@ -29,5 +18,4 @@ mac-os
 other-coprocessors
 advanced-cmd
 romi
-gloworm
 ```

docs/source/docs/installation/sw_install/other-coprocessors.md → docs/source/docs/advanced-installation/sw_install/other-coprocessors.md

@@ -23,13 +23,13 @@ $ sudo reboot now
 Your co-processor will require an Internet connection for this process to work correctly.
 :::
 
-For installation on any other co-processors, we recommend reading the {ref}`advanced command line documentation <docs/installation/sw_install/advanced-cmd:Advanced Command Line Usage>`.
+For installation on any other co-processors, we recommend reading the {ref}`advanced command line documentation <docs/advanced-installation/sw_install/advanced-cmd:Advanced Command Line Usage>`.
 
 ## Updating PhotonVision
 
 PhotonVision can be updated by downloading the latest jar file, copying it onto the processor, and restarting the service.
 
-For example, from another computer, run the following commands. Substitute the correct username for "\[user\]" (e.g. Raspberry Pi uses "pi", Orange Pi uses "orangepi".)
+For example, from another computer, run the following commands. Substitute the correct username for "\[user\]" ( Provided images use username "pi")
 
 ```bash
 $ scp [jar name].jar [user]@photonvision.local:~/

docs/source/docs/advanced-installation/sw_install/romi.md

@@ -0,0 +1,23 @@
+# Romi Installation
+
+The [Romi](https://docs.wpilib.org/en/latest/docs/romi-robot/index.html) is a small robot that can be controlled with the WPILib software. The main controller is a Raspberry Pi that must be imaged with [WPILibPi](https://docs.wpilib.org/en/latest/docs/romi-robot/imaging-romi.html) .
+
+## Installation
+
+The WPILibPi image includes FRCVision, which reserves USB cameras; to use PhotonVision, we need to edit the `/home/pi/runCamera` script to disable it. First we will need to make the file system writeable; the easiest way to do this is to go to `10.0.0.2` and choose "Writable" at the top.
+
+SSH into the Raspberry Pi (using Windows command line, or a tool like [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/) ) at the Romi's default address `10.0.0.2`. The default user is `pi`, and the password is `raspberry`.
+
+Follow the process for installing PhotonVision on {ref}`"Other Debian-Based Co-Processor Installation" <docs/advanced-installation/sw_install/other-coprocessors:Other Debian-Based Co-Processor Installation>`. As it mentions this will require an internet connection so plugging into the ethernet jack on the Raspberry Pi will be the easiest solution. The pi must remain writable!
+
+Next, from the SSH terminal, run `sudo nano /home/pi/runCamera` then arrow down to the start of the exec line and press "Enter" to add a new line. Then add `#` before the exec command to comment it out. Then, arrow up to the new line and type `sleep 10000`. Hit "Ctrl + O" and then "Enter" to save the file. Finally press "Ctrl + X" to exit nano. Now, reboot the Romi by typing `sudo reboot`.
+
+```{image} images/nano.png
+
+```
+
+After it reboots, you should be able to [locate the PhotonVision UI](https://photonvision.github.io/gloworm-docs/docs/quickstart/#finding-gloworm) at: `http://10.0.0.2:5800/`.
+
+:::{warning}
+In order for settings, logs, etc. to be saved / take effect, ensure that PhotonVision is in writable mode.
+:::

docs/source/docs/apriltag-pipelines/2D-tracking-tuning.md

@@ -1,6 +1,6 @@
 # 2D AprilTag Tuning / Tracking
 
-## Tracking Apriltags
+## Tracking AprilTags
 
 Before you get started tracking AprilTags, ensure that you have followed the previous sections on installation, wiring and networking. Next, open the Web UI, go to the top right card, and switch to the "AprilTag" or "Aruco" type. You should see a screen similar to the one below.
 

docs/source/docs/apriltag-pipelines/about-apriltags.md

@@ -1,4 +1,4 @@
-# About Apriltags
+# About AprilTags
 
 ```{image} images/pv-apriltag.png
 :align: center

docs/source/docs/contributing/building-docs.md

@@ -18,7 +18,7 @@ You must install a set of Python dependencies in order to build the documentatio
 
 In order to build the documentation, you can run the following command in the docs sub-folder. This will automatically build docs every time a file changes, and serves them locally at `localhost:8000` by default.
 
-`~/photonvision/docs$ sphinx-autobuild --open-browser source/_build/html`
+`~/photonvision/docs$ sphinx-autobuild --open-browser source source/_build/html`
 
 ## Opening the Documentation
 

docs/source/docs/description.md

@@ -2,7 +2,7 @@
 
 ## Description
 
-PhotonVision is a free, fast, and easy-to-use vision processing solution for the *FIRST*Robotics Competition. PhotonVision is designed to get vision working on your robot *quickly*, without the significant cost of other similar solutions.
+PhotonVision is a free, fast, and easy-to-use vision processing solution for the _FIRST_ Robotics Competition. PhotonVision is designed to get vision working on your robot _quickly_, without the significant cost of other similar solutions.
 Using PhotonVision, teams can go from setting up a camera and coprocessor to detecting and tracking AprilTags and other targets by simply tuning sliders. With an easy to use interface, comprehensive documentation, and a feature rich vendor dependency, no experience is necessary to use PhotonVision. No matter your resources, using PhotonVision is easy compared to its alternatives.
 
 ## Advantages

docs/source/docs/examples/aimingatatarget.md

@@ -7,15 +7,15 @@ The following example is from the PhotonLib example repository ([Java](https://g
 - A Robot
 - A camera mounted rigidly to the robot's frame, cenetered and pointed forward.
 - A coprocessor running PhotonVision with an AprilTag or Aurco 2D Pipeline.
-- [A printout of Apriltag 7](https://firstfrc.blob.core.windows.net/frc2024/FieldAssets/Apriltag_Images_and_User_Guide.pdf), mounted on a rigid and flat surface.
+- [A printout of AprilTag 7](https://firstfrc.blob.core.windows.net/frc2024/FieldAssets/Apriltag_Images_and_User_Guide.pdf), mounted on a rigid and flat surface.
 
 ## Code
 
-Now that you have properly set up your vision system and have tuned a pipeline, you can now aim your robot at an AprilTag using the data from PhotonVision. The *yaw* of the target is the critical piece of data that will be needed first.
+Now that you have properly set up your vision system and have tuned a pipeline, you can now aim your robot at an AprilTag using the data from PhotonVision. The _yaw_ of the target is the critical piece of data that will be needed first.
 
 Yaw is reported to the roboRIO over Network Tables. PhotonLib, our vender dependency, is the easiest way to access this data. The documentation for the Network Tables API can be found {ref}`here <docs/additional-resources/nt-api:Getting Target Information>` and the documentation for PhotonLib {ref}`here <docs/programming/photonlib/adding-vendordep:What is PhotonLib?>`.
 
-In this example, while the operator holds a button down, the robot will turn towards the AprilTag using the P term of a PID loop. To learn more about how PID loops work, how WPILib implements them, and more, visit  [Advanced Controls (PID)](https://docs.wpilib.org/en/stable/docs/software/advanced-control/introduction/index.html) and [PID Control in WPILib](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/controllers/pidcontroller.html#pid-control-in-wpilib).
+In this example, while the operator holds a button down, the robot will turn towards the AprilTag using the P term of a PID loop. To learn more about how PID loops work, how WPILib implements them, and more, visit [Advanced Controls (PID)](https://docs.wpilib.org/en/stable/docs/software/advanced-control/introduction/index.html) and [PID Control in WPILib](https://docs.wpilib.org/en/stable/docs/software/advanced-controls/controllers/pidcontroller.html#pid-control-in-wpilib).
 
 ```{eval-rst}
 .. tab-set::