Update Formatting and Remove Deprecated Docs (#66)

* Remove outdated doc page
Replace redundant docs with a link
Reformat docs for numbered and nested lists

* Fix link to existing documentation

* Minor updates to Debos doc wording

* Troubleshoot nested list rendering

---------

Co-authored-by: Daniel McKnight <daniel@neon.ai>

docs/diana/backend.md

@@ -29,39 +29,40 @@ We recommend you use a [Python virtual environment](https://docs.python.org/3/li
 
 1. Create a Python virtual environment:
 
-```
-python3.10 -m venv venv
-```
+    ```
+    python3.10 -m venv venv
+    ```
 
 2. Open a new terminal window. Activate the Python virtual environment in this new window:
 
-```
-. venv/bin/activate
-```
+    ```
+    . venv/bin/activate
+    ```
 
-Using this new window, proceed with the instructions.
+    Using this new window, proceed with the instructions.
 
 ## Install Diana
 
 3. Use Pip to install Diana:
 
-```
-pip install --pre neon-diana-utils
-```
-
-This command installs the newest pre-release version, which is described in this tutorial. 
-
-**Warning:** You can use `pip install neon-diana-utils` to install the current stable version. Version 1.0.0 includes Helm chart support. For information on installing and running older versions, see [the archived documentation in the README file](https://github.com/NeonGeckoCom/neon-diana-utils/blob/dev/README.md).
+    ```
+    pip install --pre neon-diana-utils
+    ```
 
-For more information on the available versions of Diana, see [the Python Package Index repo for Neon Diana](https://pypi.org/project/neon-diana-utils/).
+    This command installs the newest pre-release version, which is described in this tutorial. 
+    
+    **Warning:** You can use `pip install neon-diana-utils` to install the current stable version. Version 1.0.0 includes Helm chart support. For information on installing and running older versions, see [the archived documentation in the README file](https://github.com/NeonGeckoCom/neon-diana-utils/blob/dev/README.md).
+    
+    For more information on the available versions of Diana, see [the Python Package Index repo for Neon Diana](https://pypi.org/project/neon-diana-utils/).
 
 4. Verify Diana is installed:
 
-```
-diana --version
-```
+    ```
+    diana --version
+    ```
 
-**Tip:** If your computer does not recognize this command, you may need to add `~/.local/bin` to your $PATH with a command like `export PATH=$PATH:/home/${USER}/.local/bin`.
+    **Tip:** If your computer does not recognize this command, you may need to 
+    add `~/.local/bin` to your $PATH with a command like `export PATH=$PATH:/home/${USER}/.local/bin`.
 
 Use `diana --help` for detailed information about Diana and its commands.
 
@@ -105,103 +106,110 @@ newgrp microk8s
 
 5. Start Microk8s:
 
-```
-microk8s start
-```
+    ```
+    microk8s start
+    ```
 
 6. Enable the services for persistent storage, DNS, and the Kubernetes dashboard:
 
-```
-microk8s enable hostpath-storage
-microk8s enable dns
-microk8s enable dashboard
-```
+    ```
+    microk8s enable hostpath-storage
+    microk8s enable dns
+    microk8s enable dashboard
+    ```
 
 7. Enable the MetalLB service:
 
-```
-microk8s enable metallb
-```
-
-At the prompt, enter a subnet  which is not being used by your router. For example: 
-
-```
-10.10.10.10-10.10.10.10
-```
-
-Note: Unless you plan on adding multiple nodes, this range only needs one address.
+    ```
+    microk8s enable metallb
+    ```
+    
+    At the prompt, enter a subnet  which is not being used by your router. For example: 
+    
+    ```
+    10.10.10.10-10.10.10.10
+    ```
+    
+    Note: Unless you plan on adding multiple nodes, this range only needs one address.
 
 8. After Microk8s is running, use `microk8s kubectl create token default` to create a Microk8s token.
 
-9. In the new terminal window, use `microk8s kubectl port-forward -n kube-system service/kubernetes-dashboard 1443:443` to forward the dashboard port. 
+9. In the new terminal window, use 
+    `microk8s kubectl port-forward -n kube-system service/kubernetes-dashboard 1443:443` 
+    to forward the dashboard port. 
 
-You can now access your Kubernetes dashboard in a browser at https://localhost:1443/ using the token you created in step 2. 
+    You can now access your Kubernetes dashboard in a browser at https://localhost:1443/ using the token you created in step 2. 
 
-10. The process in this terminal needs to keep running. Either background the process, or leave this terminal window open and open a new terminal window to continue working.
+10. The process in this terminal needs to keep running. Either background the process, 
+    or leave this terminal window open and open a new terminal window to continue working.
 
 ### Set Up DNS
 
 The ingress controller needs URLs to be mapped to services. There are a number of different ways you can accomplish this, depending on your networking setup. 
 
 For this guide, we will use the simple case of editing the `/etc/hosts` file.
 
-11. Edit the `/etc/hosts` file. Add one entry for the domain name of each service you intend to run. Add the canonical domain and point it to the IP address you gave MetalLB in step 3.
+11. Edit the `/etc/hosts` file. Add one entry for the domain name of each service you
+    intend to run. Add the canonical domain and point it to the IP address you gave MetalLB in step 3.
 
-For example, if you plan to run a service named `test-service` on the `diana.k8s` domain, add the following line:
+    For example, if you plan to run a service named `test-service` on the 
+    `diana.k8s` domain, add the following line:
 
-```
-10.10.10.10 test-service.diana.k8s
-```
+    ```
+    10.10.10.10 test-service.diana.k8s
+    ```
 
-This tells your computer that `test-service.diana.k8s` is at IP address `10.10.10.10`. Your computer will route all requests for `test-service.diana.k8s` to the Kubernetes cluster you set up at `10.10.10.10`, instead of looking for it on the public internet.
-
-Add one line for each service. Point each service to the same IP address.
+    This tells your computer that `test-service.diana.k8s` is at IP address 
+    `10.10.10.10`. Your computer will route all requests for `test-service.diana.k8s` 
+    to the Kubernetes cluster you set up at `10.10.10.10`, instead of looking for it on the public internet.
+    
+    Add one line for each service. Point each service to the same IP address.
 
 
 ### Prepare for Deployment
 
 12. After you set up your Kubernetes cluster and configure DNS, configure the Diana backend with:
 
-```
-diana configure-mq-backend OUTPUT_PATH
-```
-
-Replace `OUTPUT_PATH` with the directory where you want Diana to store its Helm charts and configurations. For example:
-
-```
-diana configure-mq-backend ~/neon_diana
-```
+    ```
+    diana configure-mq-backend OUTPUT_PATH
+    ```
 
-Follow the prompts to provide any necessary configuration parameters. 
+    Replace `OUTPUT_PATH` with the directory where you want Diana to store its Helm charts and configurations. For example:
+    
+    ```
+    diana configure-mq-backend ~/neon_diana
+    ```
+    
+    Follow the prompts to provide any necessary configuration parameters. 
 
-13. **Optional:** To add extra TCP ports (i.e. for RabbitMQ), update the `OUTPUT_PATH/ingress-nginx/values.yaml` file accordingly.
+13. **Optional:** To add extra TCP ports (i.e. for RabbitMQ), update the 
+    `OUTPUT_PATH/ingress-nginx/values.yaml` file accordingly.
 
 14. Deploy the NGINX ingress:
 
-```
-helm install ingress-nginx OUTPUT_PATH/ingress-common --namespace ingress-nginx --create-namespace
-```
+    ```
+    helm install ingress-nginx OUTPUT_PATH/ingress-common --namespace ingress-nginx --create-namespace
+    ```
 
-15. Edit `OUTPUT_PATH/diana-backend-values.yaml` and update any necessary configuration. At minimum, you need to update the following parameters:
+15. Edit `OUTPUT_PATH/diana-backend-values.yaml` and update any necessary configuration.
+    At minimum, you need to update the following parameters:
 
-* `domain` Change this to the domain you added to the `/etc/hosts` file in step 11.
-* `letsencrypt.email` If you are using a "real" domain, change this to the email address you want to use for the [Let's Encrypt](https://letsencrypt.org/) SSL certificate. For local testing, leave this as is.
-* `letsencrypt.server` If you are using a "real" domain, change this to a valid Let's Encrypt server address, such as `https://acme-v02.api.letsencrypt.org/directory`. For local testing, leave this as is.
+      * `domain` Change this to the domain you added to the `/etc/hosts` file in step 11.
+      * `letsencrypt.email` If you are using a "real" domain, change this to the email address you want to use for the [Let's Encrypt](https://letsencrypt.org/) SSL certificate. For local testing, leave this as is.
+      * `letsencrypt.server` If you are using a "real" domain, change this to a valid Let's Encrypt server address, such as `https://acme-v02.api.letsencrypt.org/directory`. For local testing, leave this as is.
 
 ## Deploy the Diana Backend
 
 16. Update the Helm dependency:
 
-```
-helm dependency update OUTPUT_PATH/diana-backend
-```
+    ```
+    helm dependency update OUTPUT_PATH/diana-backend
+    ```
 
 17. Use Helm to launch Diana:
 
-```
-helm install diana-backend OUTPUT_PATH/test/diana-backend --namespace backend --create-namespace
-```
-
-This creates the `backend` namespace and launches Diana into that namespace. You can change this to any namespace name you prefer. You may want to use separate namespaces for test versus production deployments, to separate the Diana backend from other deployments, or both.
-
-```
+    ```
+    helm install diana-backend OUTPUT_PATH/test/diana-backend --namespace backend --create-namespace
+    ```
+    
+    This creates the `backend` namespace and launches Diana into that namespace. You can change this to any namespace name you prefer. You may want to use separate namespaces for test versus production deployments, to separate the Diana backend from other deployments, or both.

docs/neon_os/On_the_MarkII.md

@@ -1,9 +1,12 @@
 # Neon OS on the Mark II
-This section is for content specific to the Neon AI private personal assistant on the Mycroft Mark II Device
+This section is for content specific to the Neon AI private personal assistant on the Mycroft Mark II Device.
 
 ## Making an Additional Boot Drive
 Summary: 
-To create an additional bootable drive using your Mark II, plug a second USB or an SSD into the right hand blue port, and say "Hey Neon, make bootable media" then follow the prompts. When finished, shut down your device, move the new drive into the first port and plug it back in. 
+To create an additional bootable drive using your Mark II, plug a second USB or 
+an SSD into the right hand blue port, and say "Hey Neon, make bootable media" 
+then follow the prompts. When finished, shut down your device, move the new drive 
+into the first port and plug it back in. 
 
 ### Detailed Instructions 
 **Supplies needed:**
@@ -29,15 +32,18 @@ Select the alert by touching the alert icon, and then the words of the alert its
 8. Unplug your original drive, and move the new drive over into the upper left USB port.
 9. Plug power back in and Neon will boot up from the new drive. 
 
+> If you do not have a functioning Mark 2 device, see the 
+  [Installation Instructions](./neon_os_installation.md#installing-a-downloaded-image-to-a-usb-drive).
 
 
-### Troubleshooting and Tech Support with the Neon OS on the Mycroft Mark II
+
+### Troubleshooting and Tech Support
 
 Here is our troubleshooting walk-through, and I am also available for a personal tech support video call if you prefer more in-person assistance. 
 
 **The first things to check are the power and your USB boot drive:**
 
-​	**Start by unplugging your Mark II.**
+**Start by unplugging your Mark II.**
 
 1. The boot drive (either a USB memory key or SSD) should be securely plugged into the top left USB port, which is port 0. 
 2. There should be no other USB drives plugged in for the first boot.
@@ -83,39 +89,11 @@ Here is our troubleshooting walk-through, and I am also available for a personal
 
 
 
-**How to image or re-image a drive:**
-
-1. Download the Neon OS to your computer from [here](https://2222.us/app/files/neon_images/pi/mycroft_mark_2/recommended_mark_2.img.xz) - or use the link [here on the Neon.AI webpage](https://neon.ai/NeonAIforMycroftMarkII). This takes several minutes or more, depending on your connection speed.
-
-2. Download a (free) imaging program, if you don't have one already. We suggest [Raspberry Pi Imager](https://www.raspberrypi.com/software/) or [Balena Etcher](https://www.balena.io/etcher).
-
-3. Plug your blank or nonfunctional USB 3.0 or greater drive or SSD drive into your computer.
-
-4. Open your imager program (we suggest [Raspberry Pi Imager](https://www.raspberrypi.com/software/) or [Balena Etcher](https://www.balena.io/etcher)). 
-
-5. If using Raspberry Pi Imager:
-
-6. 1. Under the 'Operating System' menu, select 'Use Custom'.
-   2. Locate and select the Neon OS image you downloaded.
-   3. Under 'Storage', select the drive you intend to write to.
-   4. Click 'Write' and wait for the image to be written and verified. This takes several minutes, depending on your system.
-
-7. If using Balena Etcher
-
-8. 1. Under the '+', choose 'Flash from file'.
-   2. Locate and select the Neon OS image you downloaded.
-   3. Under 'Select target', select the drive you intend to write to.
-   4. Click 'Flash' and wait for the image to be written and verified. This takes several minutes, depending on your system.
-
-9. Remove the USB or SSD drive from your computer.
-
-10. Disconnect power from your Mark II.
-
-11. Plug the newly imaged USB drive into the top left USB port on your Mark II (Port 0).
-
-12. Reconnect power to your Mark II.
+#### How to image or re-image a drive
+See the [Installation Instructions](./neon_os_installation.md#installing-a-downloaded-image-to-a-usb-drive)
+for instructions on how to create a Neon OS drive.
 
-13. After starting up, you will be guided through connecting to WiFi.
+> After starting up, you will be guided through connecting to WiFi.
 
 
 

docs/neon_os/neon_debos.md

@@ -1,11 +1,11 @@
 # Embedded device images
-This repo contains [debos](https://github.com/go-debos/debos) recipes for building base images for embedded voice assistant
+This repo contains [debos](https://github.com/go-debos/debos) recipes for building OS images for embedded voice assistant
 devices. Images generated here are intended to include all dependencies, drivers, and OS-level configuration that an assistant
 device might need, such as Camera Drivers, wifi-connect, QT packages, Vocal Fusion Drivers, etc.
 
 ## Available recipes
-- debian-base-image-rpi4.yml: Debian Bookworm image with updated RPi kernel, RPi userland binaries, libcamera, 
-  wifi-connect, SJ-201/Vocalfusion drivers, and a Splash Screen.
+- `debian-neon-image.yml`: Default image that runs Neon on an edge device.
+- `debian-node-image.yml`: Node image that connects to a central Neon instance.
 
 ## Repository Structure
 Each directory contains numbered files or directories; earlier numbers correspond to earlier build stages, and 

docs/neon_os/neon_image_recipe.md

@@ -1,5 +1,5 @@
 # neon-image-recipe
-Make a Pi image from scratch.
+*DEPRECATED PROJECT* Make a Pi image from scratch.
 - [Core Configuration](#core_configuration) - Base configuration of ubuntu server
 - [Network Manager](#network_manager) - Configures networking to allow for wifi configuration via
   [wifi-connect](https://github.com/balena-os/wifi-connect).

docs/neon_os/neon_os_installation.md

@@ -48,6 +48,7 @@ Pi device.
 
 ## Using Neon OS
 To use Neon OS:
+
 1. Turn off and unplug your Mark2.
 2. Remove any USB drives and plug your Neon OS drive into the upper left (blue) USB 3 port at the back of your Mark2.
 3. Plug your Mark2 back in and [get started](./using_neon_os.md)

docs/neon_os/neon_os_updates.md

@@ -46,6 +46,7 @@ you can connect via SSH to start the update.
 ### Update via on-device terminal
 If you have a USB keyboard available, you can open a terminal on your Neon device
 to start the update.
+
 1. Connect a USB keyboard to your Neon device.
 2. Press `ctrl`+`shift`+`F1` to open a terminal.
 3. Tap or click on the terminal.

docs/operations/git/triage_issues.md

@@ -10,9 +10,11 @@ This process applies in the following situations:
 ### Process
 - Open the new issue on GitHub.
 - Read the issue comment and verify it is valid and complete.
-  - If this is a duplicate issue, apply the `duplicate` tag, close it with a comment linking the existing issue.
-  - If the issue is mis-categorized as a bug or feature, update the PR title.
-  - If the issue is in the wrong repository, transfer it as appropriate.
+
+    - If this is a duplicate issue, apply the `duplicate` tag, close it with a comment linking the existing issue.
+    - If the issue is mis-categorized as a bug or feature, update the PR title.
+    - If the issue is in the wrong repository, transfer it as appropriate.
+
 - If you know about more context (i.e. a chat thread or forum post), add it to the issue description.
 - If more information is needed for debugging, reply to the issue asking the author to clarify.
 - Verify the correct labels are applied (`bug`, `enhancement`, `documentation`, etc.)

docs/operations/libraries/workflow_review_alpha.md

@@ -8,17 +8,18 @@ This process applies when reviewing a PR to the `dev` branch of a `library` modu
 - Complete the following. Note any issues in Review Comments before leaving a 
   review to `Request Changes`. If there are no comments or the comments do not
   require code changes, then you *may* `Approve` the PR.
-  - Review changes to imports and verify dependency minimum versions are accurate.
-  - Ensure code changes have adequate unit test coverage.
-  - Ensure there are no breaking changes.
-  - If changes replace or could replace an existing method, ensure a deprecation 
-    warning is logged in the replaced method (either `deprecated` decorator or
-    `log_deprecation` call).
-  - If tests are modified, make sure newly deprecated methods are still tested and
-    that changes do not remove any test cases.
-  - Highlight any added `TODO` or existing `TODO` comments related to the changes.
-    >   It is up to the PR author and reviewer to decide if a `TODO` must be completed
-      before merging OR if an issue can be created to address it in a later PR.
+
+    - Review changes to imports and verify dependency minimum versions are accurate.
+    - Ensure code changes have adequate unit test coverage.
+    - Ensure there are no breaking changes.
+    - If changes replace or could replace an existing method, ensure a deprecation 
+      warning is logged in the replaced method (either `deprecated` decorator or
+      `log_deprecation` call).
+    - If tests are modified, make sure newly deprecated methods are still tested and
+      that changes do not remove any test cases.
+    - Highlight any added `TODO` or existing `TODO` comments related to the changes.
+    >     It is up to the PR author and reviewer to decide if a `TODO` must be completed
+        before merging OR if an issue can be created to address it in a later PR.
 
 - Ensure the PR title and body are completed. Make any revisions necessary or
   work with the PR author to make those changes.