Update documentation

macformula · Nov 1, 2024 · 10f8b95 · 10f8b95
1 parent db6326a
commit 10f8b95
Show file tree

Hide file tree

Showing 3 changed files with 92 additions and 87 deletions.
diff --git a/docs/docs/firmware/dev-setup.md b/docs/docs/firmware/dev-setup.md
@@ -7,93 +7,6 @@ Follow these steps to begin developing in `racecar/firmware`.
 
         echo "Copy Me --->"
 
-## Create an SSH Key
-
-=== "Windows"
-
-    In an admin PowerShell terminal, enter the following command:
-
-    ```text
-    ssh-keygen -t ed25519 -C "[email protected]"
-    ```
-
-    Save to the default location `c:/Users/YOU/.ssh/id_ed25519` and do not enter a passphrase. This will allow you to use the key without entering a password every time you push to GitHub.
-
-    Continue with the following commands:
-
-    ```text
-    type c:/Users/YOU/.ssh/id_ed25519 | clip
-    Get-Service -Name ssh-agent | Set-Service -StartupType Manual
-    Start-Service ssh-agent
-    ssh-add c:/Users/YOU/.ssh/id_ed25519
-    ```
-
-=== "Linux/Mac"
-
-    In a terminal window, enter the following command:
-
-    ```text
-    ssh-keygen -t ed25519 -C "[email protected]"
-    ```
-
-    Save to the default location `~/.ssh/id_ed25519` and do not enter a passphrase. This will allow you to use the key without entering a password every time you push to GitHub.
-
-    Continue with the following commands:
-
-    ```text
-    pbcopy < ~/.ssh/id_ed25519.pub
-    eval "$(ssh-agent -s)"
-    ssh-add ~/.ssh/id_ed25519
-    ```
-
-To add the key to your GitHub account, go to <https://github.com/settings/ssh/new>.
-
-- Name your key something descriptive.
-- Select "Authentication Key" as the key type.
-- Paste the contents of `id_ed25519.pub` into the "Key" box.
-- Click "Add SSH Key".
-
-Open another terminal to test your connection to GitHub by entering the following command:
-
-```text
-ssh -T [email protected]
-```
-
-Type "yes" when it asks if you want to continue connecting.
-You should see a message like "Hi username! You've successfully authenticated, but GitHub does not provide shell access."
-
-Additional GitHub documentation can be found [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) and [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/testing-your-ssh-connection).
-
-## Enable Commit Signing
-
-!!! warning
-    You must have a verified email address on GitHub to sign commits.
-
-To add a signing key to your GitHub account, go to <https://github.com/settings/ssh/new>.
-
-- Name your key something descriptive.
-- Select "Signing Key" as the key type.
-- Paste the contents of `id_ed25519.pub` into the "Key" box.
-- Click "Add SSH Key".
-
-Update your git configuration to automatically sign commits with your key:
-
-=== "Windows"
-    ```text
-    git config --global user.signingkey c:/Users/YOU/.ssh/id_ed25519
-    git config --global gpg.format=ssh
-    git config --global commit.gpgsign true
-    ```
-
-=== "Linux/Mac"
-    ```text
-    git config --global user.signingkey ~/.ssh/id_ed25519
-    git config --global gpg.format=ssh
-    git config --global commit.gpgsign true
-    ```
-
-Additional GitHub documentation can be found [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key).
-
 ## Dependencies
 
 === "Windows"

diff --git a/docs/docs/tutorials/ssh-signing.md b/docs/docs/tutorials/ssh-signing.md
@@ -0,0 +1,91 @@
+# :material-key: SSH and Commit Signing
+
+This tutorial will guide you through setting up SSH keys and commit signing for GitHub. SSH keys are a more secure way to connect to GitHub, rather than other protocols like HTTPS. Commit signing is used to verify that commits are coming from you and have not been tampered with.
+
+!!! warning
+    You must have a verified email address on GitHub to add SSH keys and sign commits.
+
+## Create an SSH Key
+
+=== "Windows"
+
+    In an admin PowerShell terminal, enter the following command:
+
+    ```text
+    ssh-keygen -t ed25519 -C "[email protected]"
+    ```
+
+    Save to the default location `c:/Users/YOU/.ssh/id_ed25519` and do not enter a passphrase. This will allow you to use the key without entering a password every time you push to GitHub.
+
+    Continue with the following commands:
+
+    ```text
+    type c:/Users/YOU/.ssh/id_ed25519 | clip
+    Get-Service -Name ssh-agent | Set-Service -StartupType Manual
+    Start-Service ssh-agent
+    ssh-add c:/Users/YOU/.ssh/id_ed25519
+    ```
+
+=== "Linux/Mac"
+
+    In a terminal window, enter the following command:
+
+    ```text
+    ssh-keygen -t ed25519 -C "[email protected]"
+    ```
+
+    Save to the default location `~/.ssh/id_ed25519` and do not enter a passphrase. This will allow you to use the key without entering a password every time you push to GitHub.
+
+    Continue with the following commands:
+
+    ```text
+    pbcopy < ~/.ssh/id_ed25519.pub
+    eval "$(ssh-agent -s)"
+    ssh-add ~/.ssh/id_ed25519
+    ```
+
+To add the key to your GitHub account, go to <https://github.com/settings/ssh/new>.
+
+- Name your key something descriptive.
+- Select "Authentication Key" as the key type.
+- Paste the contents of `id_ed25519.pub` into the "Key" box.
+- Click "Add SSH Key".
+
+Open another terminal to test your connection to GitHub by entering the following command:
+
+```text
+ssh -T [email protected]
+```
+
+Type "yes" when it asks if you want to continue connecting.
+You should see a message like "Hi username! You've successfully authenticated, but GitHub does not provide shell access."
+
+Additional SSH GitHub documentation can be found [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) and [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/testing-your-ssh-connection).
+
+## Enable Commit Signing
+
+To add a signing key to your GitHub account, go to <https://github.com/settings/ssh/new>.
+
+- Name your key something descriptive.
+- Select "Signing Key" as the key type.
+- Paste the contents of `id_ed25519.pub` into the "Key" box.
+- Click "Add SSH Key".
+
+Update your git configuration in your terminal to automatically sign commits with your key:
+
+=== "Windows"
+    ```text
+    git config --global user.signingkey c:/Users/YOU/.ssh/id_ed25519
+    git config --global gpg.format=ssh
+    git config --global commit.gpgsign true
+    ```
+
+=== "Linux/Mac"
+    ```text
+    git config --global user.signingkey ~/.ssh/id_ed25519
+    git config --global gpg.format=ssh
+    git config --global commit.gpgsign true
+    ```
+
+Additional commit signing GitHub documentation can be found [here](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key).
+
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -119,6 +119,7 @@ nav:
     - tutorials/site-dev.md
     - tutorials/wsl-can/index.md
     - tutorials/hw-debug.md
+    - tutorials/ssh-signing.md
   - Firmware:
     - firmware/index.md
     - firmware/dev-setup.md