refactor: small general docs refactor

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" }
             ]
         }

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.
+<Cards>
+    <Card
+        href="./data-types.mdx"
+        title="Common Data Types"
+        description="Primitives, strings, lists of values, queues, and stacks, including when to use each."
+        icon={<Icon name="Variable" />}
+    />
+    <Card
+        href="./classes.mdx"
+        title="Writing Classes"
+        description="Class members, constructors, header files, source files, and using a class in a program."
+        icon={<Icon name="FileCode2" />}
+    />
+</Cards>

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.
+<Cards>
+    <Card
+        href="./pull-requests.mdx"
+        title="Pull Requests & Collaboration"
+        description="Working in parallel on the same branch, and how we open and review PRs."
+        icon={<Icon name="GitPullRequest" />}
+    />
+    <Card
+        href="./development-practices.mdx"
+        title="Development Practices"
+        description="Branch naming and commit message conventions."
+        icon={<Icon name="GitBranch" />}
+    />
+    <Card
+        href="./repo-practices.mdx"
+        title="Repository Practices"
+        description="Repo naming, and what makes a repo pleasant to develop in."
+        icon={<Icon name="FolderGit2" />}
+    />
+    <Card
+        href="./rebasing.mdx"
+        title="Commit Rebasing"
+        description="Cleaning up commit history with interactive rebase."
+        icon={<Icon name="History" />}
+    />
+</Cards>

content/general/docs/general-docs.mdx → 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)
+<Cards>
+    <Card
+        href="./software-install/windows.mdx"
+        title="Windows"
+        description="Winget, WSL2, Docker, Git, and VSCode."
+        icon={<WindowsIcon />}
+    />
+    <Card
+        href="./software-install/macos.mdx"
+        title="MacOS"
+        description="Homebrew, Docker, Git, and VSCode."
+        icon={<MacOSIcon />}
+    />
+    <Card
+        href="./software-install/linux.mdx"
+        title="Linux"
+        description="Docker, Git, and VSCode."
+        icon={<LinuxIcon />}
+    />
+</Cards>
 
-## 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)

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.
 

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)**.