diff --git a/content/general/docs.config.json b/content/general/docs.config.json index 647ba14..7ffcfc0 100644 --- a/content/general/docs.config.json +++ b/content/general/docs.config.json @@ -4,7 +4,7 @@ "description": "General TrickFire documentation", "icon": "BookOpen", "sidebar": [ - { "label": "General Documentation", "slug": "general-docs" }, + { "label": "General Documentation", "slug": "index" }, { "label": "Linux Basics", "slug": "linux" }, { "label": "GitHub", @@ -17,6 +17,14 @@ { "label": "Commit Rebasing", "slug": "github/rebasing" } ] }, + { + "label": "Python", + "items": [ + { "label": "Overview", "slug": "python/general" }, + { "label": "Common Data Types", "slug": "python/data-types" }, + { "label": "Writing Classes", "slug": "python/classes" } + ] + }, { "label": "C++", "items": [ @@ -28,10 +36,9 @@ { "label": "ROS 2", "slug": "ros" }, { "label": "Software Install", - "icon": "Download", "items": [ - { "label": "macOS", "slug": "software-install/macos" }, { "label": "Windows", "slug": "software-install/windows" }, + { "label": "MacOS", "slug": "software-install/macos" }, { "label": "Linux", "slug": "software-install/linux" } ] } diff --git a/content/general/docs/cpp/general.mdx b/content/general/docs/cpp/general.mdx index bfd17d4..ef416a6 100644 --- a/content/general/docs/cpp/general.mdx +++ b/content/general/docs/cpp/general.mdx @@ -12,5 +12,17 @@ General knowledge and guidelines for writing C++ code for the club. These pages ## What's covered -- **[Common Data Types](./data-types)** - primitives, strings, lists of values, queues, and stacks, including when to use each. -- **[Writing Classes](./classes)** - class members, constructors, header files, source files, and using a class in a program. + + } + /> + } + /> + diff --git a/content/general/docs/github/general.mdx b/content/general/docs/github/general.mdx index 0eb5fbb..22a4ea9 100644 --- a/content/general/docs/github/general.mdx +++ b/content/general/docs/github/general.mdx @@ -12,7 +12,29 @@ General guidelines for how we work with GitHub throughout the club, branch and c ## What's covered -- **[Pull Requests & Collaboration](./pull-requests)** - working in parallel on the same branch, and how we open and review PRs. -- **[Development Practices](./development-practices)** - branch naming and commit message conventions. -- **[Repository Practices](./repo-practices)** - repo naming, and what makes a repo pleasant to develop in. -- **[Commit Rebasing](./rebasing)** - cleaning up commit history with interactive rebase. + + } + /> + } + /> + } + /> + } + /> + diff --git a/content/general/docs/general-docs.mdx b/content/general/docs/index.mdx similarity index 52% rename from content/general/docs/general-docs.mdx rename to content/general/docs/index.mdx index 89eff1a..63bfec9 100644 --- a/content/general/docs/general-docs.mdx +++ b/content/general/docs/index.mdx @@ -10,12 +10,31 @@ These are some general docs and suggestions for writing software here at trickfi We use a few things that you need to make sure you have installed on your machine, mainly `Docker`, `Git`, and `Visual studio code`. Below are the installation guides for all operating systems. -[Windows](./software-install/windows.mdx) -[MacOS](./software-install/macos.mdx) -[Linux](./software-install/linux.mdx) + + } + /> + } + /> + } + /> + -## AI Assisted coding. +## AI Assisted coding -While we are a educational organization we are aware that in industry more and more code is being written with the assistance of AI then in the past few years. However, we recommend that you as an individual should try your best to learn the technologies, frameworks, and programming languages on your own before you start trying to contribute AI generated code. Trickfire as an organization cares more about you as an inidivudual learning, not as much the speed of the results, we understand that you may be new to this or learning something new. If you are contributing AI generated code, you should be able to explain what each part of the code you are contributing does as if you had written it yourself. +While we are a educational organization we are aware that in industry more and more code is being written with the assistance of AI then in the past few years. However, we recommend that you as an individual should try your best to learn the technologies, frameworks, and programming languages on your own before you start trying to contribute AI generated code. + +Trickfire as an organization cares more about you as an inidivudual learning, not as much the speed of the results, we understand that you may be new to this or learning something new. If you are contributing AI generated code, you should be able to explain what each part of the code you are contributing does as if you had written it yourself. Make sure that you still continue to follow software standards if you do end up generating AI code. In the case of writing AI generated code make sure to follow the REPO's `CLAUDE.md` if there is one, the dashboard has one specifically for this purpose. [Link to file](https://github.com/TrickfireRobotics/dashboard/blob/main/CLAUDE.md) diff --git a/content/general/docs/linux.mdx b/content/general/docs/linux.mdx index 699d9e9..d41649b 100644 --- a/content/general/docs/linux.mdx +++ b/content/general/docs/linux.mdx @@ -112,7 +112,7 @@ grep -r "publisher" . Every file has an owner and a set of permissions controlling who can read, write, or execute it. You'll mostly interact with this through `sudo`, short for "superuser do", which temporarily runs a command with administrator privileges. You'll need it for things like installing software or managing system services. ```bash title="Example" -sudo apt-get update +sudo apt update ``` You'll be asked for your password the first time you use `sudo` in a while. Nothing will appear on screen as you type it, that's normal, just type it and press enter. @@ -126,7 +126,7 @@ If a file isn't executable and you need it to be (a script you downloaded, for e ## Package managers -A package manager installs and updates software from the command line instead of downloading installers from websites. On Ubuntu/Debian, that's `apt` or `apt-get`, for example `sudo apt-get install git`. +A package manager installs and updates software from the command line instead of downloading installers from websites. On Ubuntu/Debian, that's `apt` or `apt`, for example `sudo apt install git`. See the [Software Install](./software-install/linux.mdx) guide for the specific commands we use to set up Docker, Git, and VSCode. diff --git a/content/general/docs/python/classes.mdx b/content/general/docs/python/classes.mdx new file mode 100644 index 0000000..de850c4 --- /dev/null +++ b/content/general/docs/python/classes.mdx @@ -0,0 +1,106 @@ +--- +title: Writing Classes +description: Defining a Python class with attributes, methods, and a usage example +--- + +A class groups related data and functions into a type you can use in your program. An **object** is one instance of that type: a `Motor` class describes what a motor stores and does, while `left_motor` and `right_motor` are separate objects with their own values. + +Here is a small `Motor` class that stores a name and a requested speed. It does not communicate with hardware. + +## Writing the class + +Unlike C++, Python has no separate header and source file; a class is defined entirely in one place. + +```python title="motor.py" +class Motor: + def __init__(self, name: str): + self.name = name + self.speed = 0.0 + + def set_speed(self, speed: float): + self.speed = speed + + def stop(self): + self.speed = 0.0 + + def get_speed(self) -> float: + return self.speed +``` + +### The constructor and `self` + +`__init__` is the **constructor**. Python calls it automatically when you create an object. The first parameter of every method, conventionally named `self`, refers to the object the method was called on; you don't pass it explicitly when calling the method. + +Assigning to `self.name` inside `__init__` creates an attribute on that object. Attributes don't need to be declared anywhere in advance. + +### Public and private members + +Python doesn't enforce `public` or `private` the way C++ does. By convention, a name prefixed with a single underscore, such as `_speed`, signals that it's internal and callers shouldn't touch it directly, even though nothing stops them. + +```python title="motor.py" +class Motor: + def __init__(self, name: str): + self.name = name + self._speed = 0.0 # Convention: internal, not part of the public interface + + def set_speed(self, speed: float): + self._speed = speed + + def get_speed(self) -> float: + return self._speed +``` + +### Methods + +A method is a function defined inside a class. `set_speed` and `stop` return nothing (Python's equivalent of C++'s `void` is simply the absence of a `return` statement, or `return None`), while `get_speed` returns a `float`. The `-> float` is a return type hint; like the parameter hints, it documents intent but isn't enforced at runtime. + +## Using the class + +```python title="main.py" +from motor import Motor + +left_motor = Motor("left") +right_motor = Motor("right") + +left_motor.set_speed(0.5) +right_motor.set_speed(0.25) + +print(f"Left speed: {left_motor.get_speed()}") +print(f"Right speed: {right_motor.get_speed()}") + +left_motor.stop() +print(f"Left after stopping: {left_motor.get_speed()}") +``` + +Use the dot operator to call a method on an object, same as C++. Each object stores its own `name` and `speed`, so changing `left_motor` does not change `right_motor`. + +## Relating classes to ROS + +A ROS 2 node written in Python is just a class that inherits from `rclpy.node.Node`. Attributes you set in `__init__`, such as a publisher or subscriber, work exactly like the `Motor` attributes above. + +```python title="ExampleNode.py" +import rclpy +from rclpy.node import Node +from std_msgs.msg import String + + +class BasicNode(Node): + def __init__(self): + super().__init__("BasicNodePractice") + self._publisher = self.create_publisher(String, "our_publisher", 10) + self._subscriber = self.create_subscription( + String, "some_other_topic", self._subscriber_callback, 10 + ) + + def publish_some_data(self, data: str): + pub_data = String() + pub_data.data = data + self._publisher.publish(pub_data) + + def _subscriber_callback(self, msg: String): + print("Received data: " + msg.data) +``` + +`super().__init__("BasicNodePractice")` calls the constructor of `Node`, the class `BasicNode` inherits from, and gives the node its name. `self._publisher` and `self._subscriber` are attributes just like `self.name` was on `Motor`, created once in `__init__` and used by the node's methods afterward. + +For the full picture of topics, services, and publishers and subscribers in Python and C++, see **[ROS 2](./../ros.mdx)**. diff --git a/content/general/docs/python/data-types.mdx b/content/general/docs/python/data-types.mdx new file mode 100644 index 0000000..81ad059 --- /dev/null +++ b/content/general/docs/python/data-types.mdx @@ -0,0 +1,177 @@ +--- +title: Common Data Types +description: Choosing primitives, strings, lists, dictionaries, sets, queues, and stacks in Python +--- + +Every value in Python has a type, but a variable itself is just a name bound to a value. You don't declare a variable's type; Python figures it out from the value you assign. + +## Primitives + +| Type | Use case | +| ------- | -------------------------------------------------- | +| `bool` | A true or false value | +| `int` | Whole numbers, with no fixed size limit | +| `float` | Floating-point measurements | +| `str` | Text, a single character is just a length-1 string | +| `None` | The absence of a value | + +### Declaring and assigning variables + +Write a name and a value; Python infers the type from the value. + +```python +wheel_count = 6 +completed_commands = 0 +distance_meters = 2.5 +enabled = False + +# Updating values +completed_commands = 1 +enabled = True +``` + + + Python doesn't require a type annotation, but you can add one to document intent. It is not + enforced at runtime. + + ```python + wheel_count: int = 6 + max_speed: float = 1.5 + ``` + + + +## Strings + +Use `str` for text. Single and double quotes both work and mean the same thing; pick one and stay consistent within a file. + +```python +direction = "forward" +label = 'left motor' +``` + +Use an f-string to build a string from variables. + +```python +speed = 0.5 +message = f"Setting speed to {speed}" +``` + +## Containers + +A container stores multiple values. + +| Type | When to use it | Mutable | +| ------- | ------------------------------------------------------ | ------- | +| `list` | A sequence that can grow, with access by index | Yes | +| `tuple` | A fixed sequence of values that shouldn't change | No | +| `dict` | Look up a value by a key instead of a position | Yes | +| `set` | A collection of unique values with no guaranteed order | Yes | + +All four support `len()` to report how many elements they hold. + +## Lists of values + +### A general-purpose sequence: `list` + +If you want a "list" of values, use `list`. It can grow as needed and lets you access an element by its position. + +```python +distances = [1.2, 2.4, 3.6] +distances.append(4.8) # Add an element at the end + +first_distance = distances[0] # Indexes start at 0 +distances[1] = 2.5 # Update the second element + +total_distance = 0.0 +for distance in distances: + total_distance += distance + +if distances: + distances.pop() # Remove the last element +``` + +Indexing with `[]` raises an `IndexError` if the index is out of range, unlike C++'s unchecked `[]`. An empty list is falsy, so `if distances:` is a common way to check it has elements. + +### Fixed sequences: `tuple` + +A `tuple` looks like a `list` but can't be modified after it's created. Use it for values that belong together and shouldn't change, such as a coordinate pair. + +```python +position = (1.5, 2.0) # (x, y) +x, y = position # Unpacking + +# position[0] = 3.0 # Error: tuples don't support item assignment +``` + +### Key-value pairs: `dict` + +Use a `dict` when you want to look values up by a key rather than a position. + +```python +motor_speeds = {"left": 0.5, "right": 0.25} +motor_speeds["left"] = 0.75 # Update a value +motor_speeds["back"] = 0.0 # Add a new key + +for name, speed in motor_speeds.items(): + print(f"{name}: {speed}") + +if "left" in motor_speeds: + del motor_speeds["left"] +``` + +Accessing a missing key with `[]` raises a `KeyError`. Use `.get("left", 0.0)` to provide a default instead of raising. + +### Unique values: `set` + +A `set` stores unique values and is useful for membership checks or removing duplicates. + +```python +seen_ids = {1, 2, 3} +seen_ids.add(4) +seen_ids.add(2) # No effect, 2 is already present + +if 3 in seen_ids: + seen_ids.remove(3) +``` + +## Queues and stacks + +Python doesn't have dedicated queue and stack types in the way C++ does; `collections.deque` (double-ended queue) covers both. + +### Queues + +A queue uses **first in, first out (FIFO)** ordering, like people waiting in line. + +```python +from collections import deque + +commands = deque() +commands.append("drive") +commands.append("turn") + +while commands: + next_command = commands.popleft() + # Process next_command here: "drive", then "turn". +``` + +`append()` adds to the back, and `popleft()` removes and returns the oldest element. + +### Stacks + +A stack uses **last in, first out (LIFO)** ordering, such as retrieving the most recent action from an undo history. A plain `list` works well here since `append()` and `pop()` both operate on the end. + +```python +history = [] +history.append("move forward") +history.append("turn left") + +while history: + last_action = history.pop() + # Handle last_action here: "turn left", then "move forward". +``` + + + `list.pop(0)` removes from the front, but it has to shift every remaining element over, so it + gets slow as the list grows. Use `collections.deque` for a queue instead. + diff --git a/content/general/docs/python/general.mdx b/content/general/docs/python/general.mdx new file mode 100644 index 0000000..b77cfda --- /dev/null +++ b/content/general/docs/python/general.mdx @@ -0,0 +1,28 @@ +--- +title: Python Practices +description: Common data types, containers, and classes for writing Python code +--- + +General knowledge and guidelines for writing Python code for the club. These pages cover choosing types for your data, storing collections of values, and organizing a class. + + + Haven't used Python before? Start with [Common Data Types](./data-types), then work through + [Writing Classes](./classes) to see how data and functions fit together. + + +## What's covered + + + } + /> + } + /> + diff --git a/content/general/docs/software-install/linux.mdx b/content/general/docs/software-install/linux.mdx index 3999227..6c0f7a7 100644 --- a/content/general/docs/software-install/linux.mdx +++ b/content/general/docs/software-install/linux.mdx @@ -3,128 +3,110 @@ title: Linux description: installing docker, git, and visual studio code on a linux machine. --- - - Different Linux distributions ship with different shells by default. If the bash commands don't - work for you, try the fish commands instead. + + If you do not know your shell run `echo $SHELL` in your terminal! ## Docker -1. Open a terminal and run the following commands to install docker + + + Open a terminal and run the following commands to install docker - - + + - ```bash - # Add Docker's official apt repository - sudo apt-get update - sudo apt-get install -y ca-certificates curl - sudo install -m 0755 -d /etc/apt/keyrings - sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc - sudo chmod a+r /etc/apt/keyrings/docker.asc - - sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null < - - - ```fish - # Update your package manager and install docker - sudo pacman -Syu - sudo pacman -S docker docker-compose docker-buildx containerd - ``` - - - - - -2. Add your user to the docker group - - - If you don't do this, you'll have to run every docker command with `sudo` - + ```bash + # Add Docker's official apt repository + sudo apt update + sudo apt install -y ca-certificates curl + sudo install -m 0755 -d /etc/apt/keyrings + sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc + sudo chmod a+r /etc/apt/keyrings/docker.asc - - + sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null < - + + - ```fish - sudo gpasswd -a $USER docker - ``` + ```fish + # Update your package manager and install docker + sudo pacman -Syu + sudo pacman -S docker docker-compose docker-buildx containerd + ``` - + - + + + + Start the docker service and enable it to start on boot -3. Start the docker service and enable it to start on boot + + - - + ```bash + sudo systemctl enable --now docker + ``` - ```bash - sudo systemctl enable --now docker - ``` + + - - - - ```fish - sudo systemctl enable --now docker - ``` + ```fish + sudo systemctl enable --now docker + ``` - + - + -Log out and back in for the changes to take effect + Reboot or log out and back in for the changes to take effect. + + + Check docker is installed and working -4. Check docker is installed and working + + If you didn't add your user to the docker group, you'll need to run this command with `sudo` + - - If you didn't add your user to the docker group, you'll need to run this command with `sudo` - + + - - + ```bash + sudo docker --version + docker --version + docker run hello-world + ``` - ```bash - sudo docker --version - docker --version - docker run hello-world - ``` + + - - + ```fish + sudo docker --version + docker --version + docker run hello-world + ``` - ```fish - sudo docker --version - docker --version - docker run hello-world - ``` + - + - + You should see a few messages about docker running and how it pulled that message down. + -You should see a few messages about docker running and how it pulled that message down. + ### Docker debugging @@ -133,11 +115,11 @@ You should see a few messages about docker running and how it pulled that messag - If you get a message about not being able to connect to the docker daemon, run `sudo systemctl status docker` to check if the service is running. If it's not, run `sudo systemctl start docker` to start it. - Try uninstalling using the commands below and reinstalling with the commands above for a fresh install. If this doesn't work send a message in `general-software` and someone will respond back to you - - + + ```bash - sudo apt-get purge -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + sudo apt purge -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` @@ -153,184 +135,222 @@ You should see a few messages about docker running and how it pulled that messag ## Git -1. Go to the [Github website](https://github.com) and create an account if you don't already have one. (Make sure to remember the username and email you used to create the account.) -2. Open your terminal and run the following commands to install git + + + Go to the [Github website](https://github.com) and create an account if you don't already have one. (Make sure to remember the username and email you used to create the account) + + + Open your terminal and run the following commands to install git - - + + - ```bash - sudo apt-get update - sudo apt-get install -y git - ``` + ```bash + sudo apt update + sudo apt install -y git + ``` - - + + - ```fish - sudo pacman -Syu - sudo pacman -S git - ``` + ```fish + sudo pacman -Syu + sudo pacman -S git + ``` - + - + + + + Close and reopen your terminal (this refreshes your PATH) and check it exists by running `git --version` + + + Next to configure your username run -3. Close and reopen your terminal (this refreshes your PATH) and check it exists by running `git --version` -4. Next to configure your username run + + - - + ```bash + git config --global user.name "Your username here" + git config --global user.email "Your email here" + ``` - ```bash - git config --global user.name "Your username here" - git config --global user.email "Your email here" - ``` + + - - + ```fish + git config --global user.name "Your username here" + git config --global user.email "Your email here" + ``` - ```fish - git config --global user.name "Your username here" - git config --global user.email "Your email here" - ``` + - + + - + ### Optional Git configuration If your GitHub account is used on multiple machines you could run into issues with GitHub not properly authenticating. If this is the case, follow these steps to set up SSH keys for authentication -1. Generate an ssh key pair and add it to the ssh-agent - - - - - ```bash - ssh-keygen -t ed25519 -C "Your email here" - eval "$(ssh-agent -s)" - ssh-add ~/.ssh/id_ed25519 - ``` - - - - - ```fish - ssh-keygen -t ed25519 -C "Your email here" - eval (ssh-agent -c) - ssh-add ~/.ssh/id_ed25519 - ``` - - - - - -2. Copy the public key to your clipboard (copy the output of the command below) - - - - - ```bash - cat ~/.ssh/id_ed25519.pub - ``` - - - - - ```fish - cat ~/.ssh/id_ed25519.pub - ``` - - - - - -3. Go to github.com, click your profile in the top right and hit settings -4. In the settings menu click `SSH and GPG keys` then click `New SSH key` on that page -5. Make sure the new key's type is an Authentication key, give the key an appropriate name and then paste the contents that we copied earlier into the box. -6. Test that this works by running `ssh -T git@github.com` -7. When you clone a new repo make sure to hit the `code` button and hit `SSH` then copy that link and git clone + + + Generate an ssh key pair and add it to the ssh-agent + + + + + ```bash + ssh-keygen -t ed25519 -C "Your email here" + eval "$(ssh-agent -s)" + ssh-add ~/.ssh/id_ed25519 + ``` + + + + + ```fish + ssh-keygen -t ed25519 -C "Your email here" + eval (ssh-agent -c) + ssh-add ~/.ssh/id_ed25519 + ``` + + + + + + + Copy the public key to your clipboard (copy the output of the command below) + + + + + ```bash + cat ~/.ssh/id_ed25519.pub + ``` + + + + + ```fish + cat ~/.ssh/id_ed25519.pub + ``` + + + + + + + Go to github.com, click your profile in the top right and hit settings + + + In the settings menu click `SSH and GPG keys` then click `New SSH key` on that page + + + Make sure the new key's type is an Authentication key, give the key an appropriate name and then paste the contents that we copied earlier into the box. + + + Test that this works by running `ssh -T git@github.com` + + + When you clone a new repo make sure to hit the `code` button and hit `SSH` then copy that link and git clone + + + ## Visual Studio Code VSCode is the code editor we use for development. Follow the steps to install, set up, and configure VSCode -1. Open your terminal and run the following commands to install VSCode - - - - - ```bash - sudo apt-get update - sudo apt-get install -y wget gpg - wget -qO- https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft.gpg - - sudo tee /etc/apt/sources.list.d/vscode.sources > /dev/null < - - - ```fish - # Install yay, an AUR helper, so future AUR packages (including updates) are easy to manage - sudo pacman -S --needed base-devel git - git clone https://aur.archlinux.org/yay.git - cd yay - makepkg -si - - # Install VSCode using yay - yay -S visual-studio-code-bin - ``` - - - - - -2. Open VSCode from your applications menu, or run `code .` from a terminal to open the current folder -3. Test it by running - - - - - ```bash - code --version - ``` - - - - - ```fish - code --version - ``` - - - - - -6. We use Dev Containers on our repos so everyone gets an identical, pre-configured environment instead of installing tools by hand. Install the following extensions from the Extensions view (`Ctrl + Shift + X`): - - [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) (`ms-vscode-remote.remote-containers`), by Microsoft - - [Container Tools](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-containers) (`ms-azuretools.vscode-containers`), by Microsoft - - - The marketplace has several similarly named container/Docker extensions. Search by the extension - ID above (or paste it into the Extensions view search bar) to make sure you install the right - one. - - -7. Take the [URC-2023 Repo](https://github.com/TrickfireRobotics/urc-2023) and git clone it into an appropriate folder (I recommend making a trickfire folder), then run `code urc-2023` and vscode should open with this new repository opened -8. A notification should pop up asking if you want to reopen the folder in a container, click `Reopen in Container` and wait for the container to build. This may take a while the first time, but future builds will be much faster. + + + Open your terminal and run the following commands to install VSCode + + + + + ```bash + sudo apt update + sudo apt install -y wget gpg + wget -qO- https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft.gpg + + sudo tee /etc/apt/sources.list.d/vscode.sources > /dev/null < + + + ```fish + # Install yay, an AUR helper, so future AUR packages (including updates) are easy to manage + sudo pacman -S --needed base-devel git + git clone https://aur.archlinux.org/yay.git + cd yay + makepkg -si + + # Install VSCode using yay + yay -S visual-studio-code-bin + ``` + + + + + + + Open VSCode from your applications menu, or run `code .` from a terminal to open the current folder + + + Test it by running + + + + + ```bash + code --version + ``` + + + + + ```fish + code --version + ``` + + + + + + + We use Dev Containers on our repos so everyone gets an identical, pre-configured environment instead of installing tools by hand. Install the following extensions from the Extensions view (`Ctrl + Shift + X`): + + - [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) (`ms-vscode-remote.remote-containers`), by Microsoft + - [Container Tools](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-containers) (`ms-azuretools.vscode-containers`), by Microsoft + + + The marketplace has several similarly named container/Docker extensions. Search by the extension + ID above (or paste it into the Extensions view search bar) to make sure you install the right + one. + + + + Take the [URC-2023 Repo](https://github.com/TrickfireRobotics/urc-2023) and git clone it into an appropriate folder (I recommend making a trickfire folder), then run `code urc-2023` and vscode should open with this new repository opened + + + A notification should pop up asking if you want to reopen the folder in a container, click `Reopen in Container` and wait for the container to build. This may take a while the first time, but future builds will be much faster. + + + In the future you may need to install more extensions for specific languages, (EX: Python requires specific python extensions) but VSCode will prompt you for those usually when you open up a new repository. diff --git a/content/general/docs/software-install/macos.mdx b/content/general/docs/software-install/macos.mdx index 1e3058a..7bf51f2 100644 --- a/content/general/docs/software-install/macos.mdx +++ b/content/general/docs/software-install/macos.mdx @@ -7,24 +7,33 @@ description: installing docker, git, and visual studio code on a macos machine. To install most of the software we use on a regular basis you will need to install [Homebrew](https://brew.sh/). Homebrew is a MacOS package manager that hosts a large number of packages and software that we use on a frequent basis. To do so follow these steps. -1. Open your MacOS terminal you can do this by hitting `Command + Space` and typing in `Terminal`. -2. Copy and paste this command into your Terminal - - This will require your Mac's password since it requires some privileged permissions to - install the package manager. - - -```bash title="Terminal" -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -``` - -3. Next you need to add `brew` into your path. The installer will print a "Next steps" section in your terminal with the exact commands to run for your Mac. Copy and paste those commands into your terminal. On Apple Silicon Macs they will look like this: - -```bash title="Terminal" -echo >> /Users/"${USER}"/.zprofile -echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/"$USER"/.zprofile -eval "$(/opt/homebrew/bin/brew shellenv)" -``` + + + Open your MacOS terminal, you can do this by hitting `Command + Space` and typing in `Terminal`. + + + Copy and paste this command into your Terminal. + + + This will require your Mac's password since it requires some privileged permissions to + install the package manager. + + + ```bash title="Terminal" + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + ``` + + + Next you need to add `brew` into your path. The installer will print a "Next steps" section in your terminal with the exact commands to run for your Mac. Copy and paste those commands into your terminal. On Apple Silicon Macs they will look like this: + + ```bash title="Terminal" + echo >> /Users/"${USER}"/.zprofile + echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/"$USER"/.zprofile + eval "$(/opt/homebrew/bin/brew shellenv)" + ``` + + + If you're on an Intel Mac, Homebrew installs to `/usr/local` instead of `/opt/homebrew`, so the @@ -37,23 +46,30 @@ Page](https://github.com/orgs/Homebrew/discussions) ## Docker -1. Now that we've installed brew you can easily install docker by running + + + Now that we've installed brew you can easily install docker by running -```bash title="Terminal" -brew install --cask docker -``` + ```bash title="Terminal" + brew install --cask docker + ``` -This will install the Docker VM, Docker engine, and Docker desktop app. Make sure you don't forget to add `--cask` or you may not install all required software. + This will install the Docker VM, Docker engine, and Docker desktop app. Make sure you don't forget to add `--cask` or you may not install all required software. + + + Open Docker by hitting `Command + space` and typing in Docker you will see some permission prompts type in your password and docker will install + + + Next to check if docker is working run -2. Open Docker by hitting `Command + space` and typing in Docker you will see some permission prompts type in your password and docker will install + ```bash title="Terminal" + docker run hello-world + ``` -3. Next to check if docker is working run + You should see a few messages about docker running and how it pulled that message down. + -```bash title="Terminal" -docker run hello-world -``` - -You should see a few messages about docker running and how it pulled that message down. + ### Docker debugging @@ -64,32 +80,58 @@ If it didn't work try these debug commands. ## Git -1. Go to the [Github website](https://github.com/) and make an account skip if you have one. Remember the username and email you used to make the account. -2. Open your terminal and run `brew install git` and check if it exists by running `git` -3. Next to configure your username run `git config --global user.name "Your username here"` and `git config --global user.email "Your email here"` + + + Go to the [Github website](https://github.com/) and make an account skip if you have one. + Remember the username and email you used to make the account. + + + Open your terminal and run `brew install git` and check if it exists by running `git` + + + Next to configure your username run `git config --global user.name "Your username here"` and + `git config --global user.email "Your email here"` + + ### Optional Git configuration If your Github account is shared across multiple machines, you may run into issues with not being able to push since github wasn't able to properly authenticate, if this is the case follow these steps. -1. Run `ssh-keygen -t ed25519 -C "Your email here"` and follow the prompts on the terminal, You can set up a password but this makes authentication much harder. -2. Now run `cat ~/.ssh/id_ed25519.pub` and copy that output into you clipboard. -3. Next go to github.com, click your profile in the top right and hit settings -4. In the settings menu click `SSH and GPG keys` then click `New SSH key` on that page. -5. Make sure the new key's type is an Authentication key, give the key an appropriate name and then paste the contents that we copied earlier into the box. -6. run this command in your terminal - -```bash title="Terminal" -touch ~/.ssh/config -echo "Host * - IPQoS cs0 cs0 - AddKeysToAgent yes - UseKeychain yes - IdentityFile ~/.ssh/id_ed25519 -" >> ~/.ssh/config -``` - -7. Test that this works by running `ssh -T git@github.com` this should show a message about succesful authentication to github. + + + Run `ssh-keygen -t ed25519 -C "Your email here"` and follow the prompts on the terminal, You can set up a password but this makes authentication much harder. + + + Now run `cat ~/.ssh/id_ed25519.pub` and copy that output into you clipboard. + + + Next go to github.com, click your profile in the top right and hit settings + + + In the settings menu click `SSH and GPG keys` then click `New SSH key` on that page. + + + Make sure the new key's type is an Authentication key, give the key an appropriate name and then paste the contents that we copied earlier into the box. + + + run this command in your terminal + + ```bash title="Terminal" + touch ~/.ssh/config + echo "Host * + IPQoS cs0 cs0 + AddKeysToAgent yes + UseKeychain yes + IdentityFile ~/.ssh/id_ed25519 + " >> ~/.ssh/config + ``` + + + Test that this works by running `ssh -T git@github.com` this should show a message about succesful authentication to github. + + + This includes an extra hoop to jump through with repos you are going to be contributing to. When @@ -101,33 +143,52 @@ echo "Host * Next we will lead you through the setup for VSCode and all of the extensions we need. -1. Run `brew install --cask visual-studio-code` -2. Once the install finishes press `Command + Space` and open VSCode -3. Follow the installation steps that VSCode prompts you for. -4. Open the Command Palette (`Command + Shift + P`), search for `Shell Command: Install 'code' command in PATH`, and run it. This lets you run `code .` from the terminal to open the current folder in VSCode, which is handy once you start cloning repos. -5. Test it by opening a new terminal window and running - -```bash title="Terminal" -code --version -``` - -You should see a version number and commit hash printed out. - -6. We use Dev Containers on our repos so everyone gets an identical, pre-configured environment instead of installing tools by hand. Install the following extensions from the Extensions view (`Command + Shift + X`): - - [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) (`ms-vscode-remote.remote-containers`), by Microsoft - - [Container Tools](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-containers) (`ms-azuretools.vscode-containers`), by Microsoft - - - The marketplace has several similarly named container/Docker extensions. Search by the extension - ID above (or paste it into the Extensions view search bar) to make sure you install the right - one. - -7. Nearly finished, now take the [URC-2023 Repo](https://github.com/TrickfireRobotics/urc-2023.git) -copy the link and `git clone https://github.com/TrickfireRobotics/urc-2023.git` the repo into an -appropriate folder, then run `code urc-2023` and vscode should open with this new repository opened -8. A notification should popup that has an option that says "Reopen in Container" click that and -VSCode will start building and creating the devcontainer, make sure that docker is running in the -background before you do this otherwise this will fail. + + + Run `brew install --cask visual-studio-code` + + + Once the install finishes press `Command + Space` and open VSCode + + + Follow the installation steps that VSCode prompts you for. + + + Open the Command Palette (`Command + Shift + P`), search for `Shell Command: Install 'code' command in PATH`, and run it. This lets you run `code .` from the terminal to open the current folder in VSCode, which is handy once you start cloning repos. + + + Test it by opening a new terminal window and running + + ```bash title="Terminal" + code --version + ``` + + You should see a version number and commit hash printed out. + + + We use Dev Containers on our repos so everyone gets an identical, pre-configured environment instead of installing tools by hand. Install the following extensions from the Extensions view (`Command + Shift + X`): + + - [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) (`ms-vscode-remote.remote-containers`), by Microsoft + - [Container Tools](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-containers) (`ms-azuretools.vscode-containers`), by Microsoft + + + The marketplace has several similarly named container/Docker extensions. Search by the extension + ID above (or paste it into the Extensions view search bar) to make sure you install the right + one. + + + + Nearly finished, now take the [URC-2023 Repo](https://github.com/TrickfireRobotics/urc-2023.git) + copy the link and `git clone https://github.com/TrickfireRobotics/urc-2023.git` the repo into an + appropriate folder, then run `code urc-2023` and vscode should open with this new repository opened + + + A notification should popup that has an option that says "Reopen in Container" click that and + VSCode will start building and creating the devcontainer, make sure that docker is running in the + background before you do this otherwise this will fail. + + + A majority of our development is done inside of devcontainers, this is something that you will repeat in the future as you take on more projects. diff --git a/content/general/docs/software-install/windows.mdx b/content/general/docs/software-install/windows.mdx index 98c72bb..debc607 100644 --- a/content/general/docs/software-install/windows.mdx +++ b/content/general/docs/software-install/windows.mdx @@ -7,12 +7,19 @@ description: installing docker, git, and visual studio code on a Windows machine Windows comes with its own package manager called `winget` (the "Windows Package Manager"), and we'll use it to install everything else in this guide. It ships pre-installed as part of "App Installer" on up to date Windows 10 and Windows 11 machines. -1. Open PowerShell by hitting the `Windows` key and typing in `PowerShell`. -2. Check that winget is installed by running + + + Open PowerShell by hitting the `Windows` key and typing in `PowerShell`. + + + Check that winget is installed by running -```bash title="PowerShell" -winget --version -``` + ```bash title="PowerShell" + winget --version + ``` + + + If that command isn't found, open the Microsoft Store, search for `App Installer`, and hit @@ -23,14 +30,27 @@ winget --version Docker Desktop needs a Linux backend to actually run containers, and the one we'll use is WSL2 (Windows Subsystem for Linux). It works on Windows Home as well as Pro, unlike the older Hyper-V backend, so we'll set it up before installing Docker. -1. Open PowerShell as an Administrator, hit the `Windows` key, type in `PowerShell`, then hit `Ctrl + Shift + Enter` (or right click the result and hit "Run as administrator"). -2. Run + + + Open PowerShell as an Administrator, hit the `Windows` key, type in `PowerShell`, then hit `Ctrl + Shift + Enter` (or right click the result and hit "Run as administrator"). + + + Run + + ```bash title="PowerShell (Administrator)" + wsl --install + ``` -```bash title="PowerShell (Administrator)" -wsl --install -``` + This enables the required Windows features, installs the WSL2 kernel, and installs Ubuntu as the default Linux distribution. + + + Restart your computer when prompted. + + + After restarting, Ubuntu will open automatically and ask you to create a Linux username and password, these are separate from your Windows account so pick whatever you'd like. + -This enables the required Windows features, installs the WSL2 kernel, and installs Ubuntu as the default Linux distribution. 3. Restart your computer when prompted. 4. After restarting, Ubuntu will open automatically and ask you to create a Linux username and password, these are separate from your Windows account so pick whatever you'd like. + `wsl --install` requires Windows 10 version 2004 (Build 19041) or later, or Windows 11. If @@ -39,21 +59,31 @@ This enables the required Windows features, installs the WSL2 kernel, and instal ## Docker -1. Now that WSL2 is set up you can install Docker Desktop by running + + + Now that WSL2 is set up you can install Docker Desktop by running -```bash title="PowerShell" -winget install --id Docker.DockerDesktop -e -``` + ```bash title="PowerShell" + winget install --id Docker.DockerDesktop -e + ``` + + + Open Docker Desktop by hitting `Windows + S` and typing in Docker you will see a service agreement, accept it and let it finish starting up. + + + In Docker Desktop go to `Settings > General` and make sure `Use the WSL 2 based engine` is checked, it should already be on by default. + + + Next to check if docker is working, open a **new** PowerShell window and run -2. Open Docker Desktop by hitting `Windows + S` and typing in Docker you will see a service agreement, accept it and let it finish starting up. -3. In Docker Desktop go to `Settings > General` and make sure `Use the WSL 2 based engine` is checked, it should already be on by default. -4. Next to check if docker is working, open a **new** PowerShell window and run + ```bash title="PowerShell" + docker run hello-world + ``` -```bash title="PowerShell" -docker run hello-world -``` + You should see a few messages about docker running and how it pulled that message down. + -You should see a few messages about docker running and how it pulled that message down. + ### Docker debugging @@ -66,15 +96,25 @@ If it didn't work try these debug commands. ## Git -1. Go to the [Github website](https://github.com/) and make an account skip if you have one. Remember the username and email you used to make the account. -2. Open PowerShell and run - -```bash title="PowerShell" -winget install --id Git.Git -e --source winget -``` - -3. Close and reopen PowerShell (this refreshes your PATH) and check it exists by running `git --version` -4. Next to configure your username run `git config --global user.name "Your username here"` and `git config --global user.email "Your email here"` + + + Go to the [Github website](https://github.com/) and make an account skip if you have one. Remember the username and email you used to make the account. + + + Open PowerShell and run + + ```bash title="PowerShell" + winget install --id Git.Git -e --source winget + ``` + + + Close and reopen PowerShell (this refreshes your PATH) and check it exists by running `git --version` + + + Next to configure your username run `git config --global user.name "Your username here"` and `git config --global user.email "Your email here"` + + + ### Optional Git configuration @@ -84,31 +124,48 @@ If your Github account is shared across multiple machines, you may run into issu These steps use the OpenSSH client that ships with Windows itself rather than the one bundled with Git for Windows. To check it's available run `ssh -V` in PowerShell. If that command isn't found, go to `Settings > Apps > Optional Features > Add a feature`, search for `OpenSSH Client`, and install it. -1. Run `ssh-keygen -t ed25519 -C "Your email here"` and follow the prompts on the terminal, You can set up a password but this makes authentication much harder. -2. Set the ssh-agent service to start automatically and add your key to it, open PowerShell as an Administrator and run - -```bash title="PowerShell (Administrator)" -Get-Service ssh-agent | Set-Service -StartupType Automatic -Start-Service ssh-agent -ssh-add ~/.ssh/id_ed25519 -``` - -3. Now run `Get-Content ~/.ssh/id_ed25519.pub | clip`, this copies the key directly into your clipboard. -4. Next go to github.com, click your profile in the top right and hit settings -5. In the settings menu click `SSH and GPG keys` then click `New SSH key` on that page. -6. Make sure the new key's type is an Authentication key, give the key an appropriate name and then paste the contents that we copied earlier into the box. -7. run this command in your terminal - -```bash title="PowerShell" -New-Item -Path ~\.ssh\config -ItemType File -Force -@" -Host * - AddKeysToAgent yes - IdentityFile ~/.ssh/id_ed25519 -"@ | Add-Content ~\.ssh\config -``` - -8. Test that this works by running `ssh -T git@github.com` this should show a message about succesful authentication to github. + + + Run `ssh-keygen -t ed25519 -C "Your email here"` and follow the prompts on the terminal, You can set up a password but this makes authentication much harder. + + + Set the ssh-agent service to start automatically and add your key to it, open PowerShell as an Administrator and run + + ```bash title="PowerShell (Administrator)" + Get-Service ssh-agent | Set-Service -StartupType Automatic + Start-Service ssh-agent + ssh-add ~/.ssh/id_ed25519 + ``` + + + Now run `Get-Content ~/.ssh/id_ed25519.pub | clip`, this copies the key directly into your clipboard. + + + Next go to github.com, click your profile in the top right and hit settings + + + In the settings menu click `SSH and GPG keys` then click `New SSH key` on that page. + + + Make sure the new key's type is an Authentication key, give the key an appropriate name and then paste the contents that we copied earlier into the box. + + + run this command in your terminal + + ```bash title="PowerShell" + New-Item -Path ~\.ssh\config -ItemType File -Force + @" + Host * + AddKeysToAgent yes + IdentityFile ~/.ssh/id_ed25519 + "@ | Add-Content ~\.ssh\config + ``` + + + Test that this works by running `ssh -T git@github.com` this should show a message about succesful authentication to github. + + + This includes an extra hoop to jump through with repos you are going to be contributing to. When @@ -120,35 +177,52 @@ Host * Next we will lead you through the setup for VSCode and all of the extensions we need. -1. Run - -```bash title="PowerShell" -winget install -e --id Microsoft.VisualStudioCode -``` - -2. Once the install finishes press the `Windows` key and type in `Visual Studio Code` to open it -3. Follow the installation steps that VSCode prompts you for. -4. Open the Command Palette (`Ctrl + Shift + P`), search for `Shell Command: Install 'code' command in PATH`, and run it. This lets you run `code .` from the terminal to open the current folder in VSCode, which is handy once you start cloning repos. -5. Close and reopen PowerShell then test it by running - -```bash title="PowerShell" -code --version -``` - -You should see a version number and commit hash printed out. - -6. We use Dev Containers on our repos so everyone gets an identical, pre-configured environment instead of installing tools by hand. Install the following extensions from the Extensions view (`Ctrl + Shift + X`): - - [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) (`ms-vscode-remote.remote-containers`), by Microsoft - - [Container Tools](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-containers) (`ms-azuretools.vscode-containers`), by Microsoft - - - The marketplace has several similarly named container/Docker extensions. Search by the extension - ID above (or paste it into the Extensions view search bar) to make sure you install the right - one. - - -7. Nearly finished, now take the [URC-2023 Repo](https://github.com/TrickfireRobotics/urc-2023.git) copy the link and `git clone https://github.com/TrickfireRobotics/urc-2023.git` the repo into an appropriate folder, then run `code urc-2023` and vscode should open with this new repository opened -8. A notification should popup that has an option that says "Reopen in Container" click that and VSCode will start building and creating the devcontainer, make sure that Docker Desktop is running in the background before you do this otherwise this will fail. + + + Run + + ```bash title="PowerShell" + winget install -e --id Microsoft.VisualStudioCode + ``` + + + Once the install finishes press the `Windows` key and type in `Visual Studio Code` to open it + + + Follow the installation steps that VSCode prompts you for. + + + Open the Command Palette (`Ctrl + Shift + P`), search for `Shell Command: Install 'code' command in PATH`, and run it. This lets you run `code .` from the terminal to open the current folder in VSCode, which is handy once you start cloning repos. + + + Close and reopen PowerShell then test it by running + + ```bash title="PowerShell" + code --version + ``` + + You should see a version number and commit hash printed out. + + + We use Dev Containers on our repos so everyone gets an identical, pre-configured environment instead of installing tools by hand. Install the following extensions from the Extensions view (`Ctrl + Shift + X`): + + - [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) (`ms-vscode-remote.remote-containers`), by Microsoft + - [Container Tools](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-containers) (`ms-azuretools.vscode-containers`), by Microsoft + + + The marketplace has several similarly named container/Docker extensions. Search by the extension + ID above (or paste it into the Extensions view search bar) to make sure you install the right + one. + + + + Nearly finished, now take the [URC-2023 Repo](https://github.com/TrickfireRobotics/urc-2023.git) copy the link and `git clone https://github.com/TrickfireRobotics/urc-2023.git` the repo into an appropriate folder, then run `code urc-2023` and vscode should open with this new repository opened + + + A notification should popup that has an option that says "Reopen in Container" click that and VSCode will start building and creating the devcontainer, make sure that Docker Desktop is running in the background before you do this otherwise this will fail. + + + Docker Desktop on Windows is noticeably slower building and watching files that live on your diff --git a/next-env.d.ts b/next-env.d.ts index 9edff1c..c4b7818 100644 --- a/next-env.d.ts +++ b/next-env.d.ts @@ -1,6 +1,6 @@ /// /// -import "./.next/types/routes.d.ts"; +import "./.next/dev/types/routes.d.ts"; // NOTE: This file should not be edited // see https://nextjs.org/docs/app/api-reference/config/typescript for more information. diff --git a/src/components/mdx.tsx b/src/components/mdx.tsx index 9cfbfbf..7a70a91 100644 --- a/src/components/mdx.tsx +++ b/src/components/mdx.tsx @@ -4,6 +4,7 @@ import { Tab as TabBase, Tabs as TabsBase } from "fumadocs-ui/components/tabs"; import { Accordion, Accordions } from "fumadocs-ui/components/accordion"; import { CircleCheck, CircleX, Info, Lightbulb, TriangleAlert } from "lucide-react"; import { cn } from "@/lib/cn"; +import { resolveIcon } from "@/lib/icon"; import type { ComponentProps, CSSProperties, ReactNode } from "react"; import type { MDXComponents } from "mdx/types"; @@ -47,6 +48,41 @@ function Image({ width, center = true, className, children, ...props }: ImagePro ); } +function WindowsIcon(props: ComponentProps<"svg">) { + return ( + + + + ); +} + +function MacOSIcon(props: ComponentProps<"svg">) { + return ( + + + + ); +} + +function LinuxIcon(props: ComponentProps<"svg">) { + return ( + + + + ); +} + +interface IconProps { + /** Name of a lucide-react icon, e.g. `"GitPullRequest"`. */ + name: string; + className?: string; +} + +/** Look up any lucide-react icon by name - same registry the sidebar's `icon` config uses. */ +function Icon({ name, className = "size-4" }: IconProps) { + return resolveIcon(name, className); +} + type CalloutType = "info" | "warning" | "error" | "success" | "idea"; const calloutIcons: Record = { @@ -128,6 +164,10 @@ export function getMDXComponents(components?: MDXComponents) { Accordions, Callout, Image, + Icon, + WindowsIcon, + MacOSIcon, + LinuxIcon, ...components, } satisfies MDXComponents; }