Sailbot Workspace v1.2.0 Updates (#145)

* Revamp run instructions * Add readmes of subteam repositories * Add custom_intefaces and website readmes * Delete deleted workflow badge * Update outdated version message * Add sailbot workspace instructions to README * Rename run page to dev workflow * Fix sentence * Unify header style * Move macOS GUI admonition to beginning of section * Move run raye's software section to how to page
UBCSailbot · Jun 15, 2023 · e46e9a0 · e46e9a0
1 parent c9300b6
commit e46e9a0
Show file tree

Hide file tree

Showing 13 changed files with 265 additions and 138 deletions.
diff --git a/README.md b/README.md
@@ -1,12 +1,22 @@
 # Docs
 
-[![Publish](https://github.com/UBCSailbot/docs/actions/workflows/publish.yml/badge.svg)](https://github.com/UBCSailbot/docs/actions/workflows/publish.yml)
 [![Tests](https://github.com/UBCSailbot/docs/actions/workflows/tests.yml/badge.svg)](https://github.com/UBCSailbot/docs/actions/workflows/tests.yml)
 
-UBCSailbot software team's documentation.
+UBCSailbot software team's documentation site. It is meant to be developed in [Sailbot Workspace](https://github.com/UBCSailbot/sailbot_workspace)
+in conjunction with our other software, but doesn't have to be. There are instructions for both cases below.
 
 ## Setup
 
+### Setup in Sailbot Workspace
+
+1. Uncomment `docker-compose.docs.yml` in `.devcontainer/devcontainer.json`
+2. Rebuild the Dev Container
+
+Refer to [How to run optional programs](https://ubcsailbot.github.io/docs/main/current/sailbot_workspace/how_to/#run-optional-programs)
+for more details.
+
+### Setup By Itself
+
 1. Clone repository
 
     ```
@@ -26,14 +36,21 @@ UBCSailbot software team's documentation.
 
 ## Run
 
-### VS Code
+### Run in Sailbot Workspace
+
+After [setup](#setup-in-sailbot-workspace), the Docs site should be running on port 8000.
+
+Refer to [How to run optional programs](https://ubcsailbot.github.io/docs/main/current/sailbot_workspace/how_to/#run-optional-programs)
+for more details.
+
+### Run By Itself using VS Code
 
 1. `CTRL+P` to open Quick Open
 2. Run a launch configuration
     - "debug Run Application" runs `mkdocs serve`
     - "debug Launch Application" runs `mkdocs serve` and opens the application in a new Microsoft Edge window
 
-### Command Line
+### Run By Itself using CLI
 
 ```
 mkdocs serve
@@ -43,9 +60,14 @@ mkdocs serve
 
 This site is built using the latest versions of dependencies in [`docs/requirements.txt`](./docs/requirements.txt)
 at the time of the most recent commit to the main branch.
-To see exactly how the site will look before pushing or merging into the main branch,
-ensure your local dependencies are up to date with
+To see exactly how the site will look when deployed, ensure your local dependencies are up to date.
+
+### Update Dependencies in Sailbot Workspace
+
+Rebuild the Dev Container.
+
+### Update Dependencies By Itself
 
 ```
-pip install -Ur docs/requirements.txt --upgrade-strategy eager
+pip install -Ur docs/requirements.txt
 ```
diff --git a/docs/current/boat_simulator/overview.md b/docs/current/boat_simulator/overview.md
@@ -0,0 +1,7 @@
+!!! quote "Source code"
+
+    The source code for Boat Simulator can be found in the
+    [boat_simulator](https://github.com/UBCSailbot/boat_simulator){target=_blank} GitHub repository.
+    Its README has been copied below.
+
+--8<-- "https://raw.githubusercontent.com/UBCSailbot/boat_simulator/main/README.md"
diff --git a/docs/current/custom_interfaces/overview.md b/docs/current/custom_interfaces/overview.md
@@ -0,0 +1,7 @@
+!!! quote "Source code"
+
+    The source code for Custom Interfaces can be found in the
+    [custom_interfaces](https://github.com/UBCSailbot/custom_interfaces){target=_blank} GitHub repository.
+    Its README has been copied below.
+
+--8<-- "https://raw.githubusercontent.com/UBCSailbot/custom_interfaces/main/README.md"
diff --git a/docs/current/local_pathfinding/overview.md b/docs/current/local_pathfinding/overview.md
@@ -0,0 +1,7 @@
+!!! quote "Source code"
+
+    The source code for Local Pathfinding can be found in the
+    [local_pathfinding](https://github.com/UBCSailbot/local_pathfinding){target=_blank} GitHub repository.
+    Its README has been copied below.
+
+--8<-- "https://raw.githubusercontent.com/UBCSailbot/local_pathfinding/main/README.md"
diff --git a/docs/current/network_systems/overview.md b/docs/current/network_systems/overview.md
@@ -0,0 +1,7 @@
+!!! quote "Source code"
+
+    The source code for Network Systems can be found in the
+    [network_systems](https://github.com/UBCSailbot/network_systems){target=_blank} GitHub repository.
+    Its README has been copied below.
+
+--8<-- "https://raw.githubusercontent.com/UBCSailbot/network_systems/main/README.md"
diff --git a/docs/current/sailbot_workspace/docker_images.md b/docs/current/sailbot_workspace/docker_images.md
@@ -1,4 +1,4 @@
-# Sailbot Workspace Docker Images
+# Docker Images
 
 A table detailing the Docker images used to create the Dev Container can be found below.
 Click on an image to learn more about its features and how to update it.

diff --git a/docs/current/sailbot_workspace/how_to.md b/docs/current/sailbot_workspace/how_to.md
@@ -1,4 +1,4 @@
-# How-To
+# How-To's
 
 ## Run optional programs
 
@@ -131,3 +131,68 @@ To use your dotfiles:
 3. Run the `Dev Containers: Rebuild Container` VS Code command
 
 [^1]: [Dotfiles – What is a Dotfile and How to Create it in Mac and Linux](https://www.freecodecamp.org/news/dotfiles-what-is-a-dot-file-and-how-to-create-it-in-mac-and-linux/){target=_blank}
+
+## Run Raye's software
+
+Raye was our previous project. Her software can be run in the `raye` branch:
+
+1. Switch to the `raye` branch: `git switch raye`
+2. Rebuild the Dev Container: run the `Dev Containers: Rebuild Container` command in the
+   [VS Code command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette){target=_blank}
+
+!!! warning "`raye` branch disclaimers"
+
+    1. Since `raye` (and Raye's codebase in general) is not in active development, it may not be 100% functional
+       or contain all the features in `main`
+    2. `raye` is more memory intensive than `main` because the parent image of its Dev Container is much larger;
+       this may lead to worse performance
+
+### Build Raye's ROS packages
+
+To build Raye's ROS packages, run the following commands:
+
+```bash
+roscd
+catkin_make
+```
+
+### Run packages from different workspaces
+
+The `raye` branch has two ROS workspaces: one for Raye and one for the new project.
+To run ROS packages, you will have to source the overlay of the workspace that it is in:
+
+=== "New Project"
+
+    ```
+    srcnew
+    ```
+
+=== "Raye"
+
+    ```
+    srcraye
+    ```
+
+Then you can run launch files or package-specific executables in that workspace with:
+
+=== "New Project"
+
+    `ros2 launch ...` or `ros2 run ...`, respectively.
+
+=== "Raye"
+
+    `roslaunch ...` or `rosrun ...`, respectively.
+
+### Raye's known issues
+
+!!! bug "Run commands for Raye packages are very slow"
+
+    On non-Ubuntu-based Linux operating systems, Run commands for Raye packages may take a long time to start-up.
+    This is because the system has trouble resolving the local hostname.
+
+    To resolve this bug, run the commands below in the Dev Container:
+
+    ```bash
+    echo 'export ROS_HOSTNAME=localhost' >> ~/.bashrc
+    echo 'export ROS_MASTER_URI=http://localhost:11311' >> ~/.bashrc
+    ```
diff --git a/docs/current/sailbot_workspace/run.md b/docs/current/sailbot_workspace/run.md
diff --git a/docs/current/sailbot_workspace/setup.md b/docs/current/sailbot_workspace/setup.md
@@ -1,4 +1,4 @@
-# Sailbot Workspace Setup Instructions
+# Setup Instructions
 
 This workspace can be run on Windows, Linux, or macOS, but is the easiest to set up and performs the best on
 [Ubuntu](https://ubuntu.com/){target=_blank} and [its derivatives](https://distrowatch.com/search.php?basedon=Ubuntu){target=_blank}.