Improve Guides (#46)

docs/source/api/index.md

@@ -0,0 +1,6 @@
+# API Reference
+
+```{toctree}
+core.md
+views/index.md
+```

docs/source/conf.py

@@ -28,9 +28,11 @@
 html_theme_options = {
     "light_css_variables": {
         "color-brand-primary": "#FF67E3",
+        "color-brand-content": "#FF67E3",
     },
     "dark_css_variables": {
         "color-brand-primary": "#FF67E3",
+        "color-brand-content": "#FF67E3",
     },
 }
 

docs/source/guides/installing.md

@@ -1,9 +1,9 @@
 # Installing
 
-:::{note}
+```{note}
 If you only have the PROS VSCode extension installed, you must run
 commands in the PROS "Integrated Terminal", not your system terminal.
-:::
+```
 
 ## Prerequisites
 
@@ -17,19 +17,26 @@ Before you install robodash you must have the following:
 
 ## Add the depot
 
-Before adding robodash to your project, you'll need to register the depot with the PROS CLI. A depot is a remote file that informs the PROS CLI of templates that exist and where they can be installed from. You can run the command below to add the depot.
+Before adding robodash to your project, you'll need to register the depot with
+the PROS CLI. A depot is a remote file that informs the PROS CLI of templates
+that exist and where they can be installed from. You can run the command below
+to add the depot.
 
 ```
 pros c add-depot robodash https://raw.githubusercontent.com/unwieldycat/robodash/depot/stable.json
 ```
 
 ### Or don't
 
-Alternatively, you can download and register an individual version of robodash by downloading it from the releases tab on the GitHub page and registering it with `pros c fetch [email protected]`. This is not recommended since you will have to manually repeat this step as robodash updates.
+Alternatively, you can download and register an individual version of robodash
+by downloading it from the releases tab on the GitHub page and registering it
+with `pros c fetch [email protected]`. This is not recommended since you will
+have to manually repeat this step as robodash updates.
 
 ## Apply to project
 
-Now let's add robodash to a project. Open the project you wish to use the robodash in and run the command below to apply it to your project.
+Now let's add robodash to a project. Open the project you wish to use the
+robodash in and run the command below to apply it to your project.
 
 ```
 pros c apply robodash

docs/source/guides/ui.md

@@ -27,4 +27,4 @@ clicking the bell icon to reopen the alert menu.
 ![Alert button](../img/alert_button.png)
 
 If multiple alerts appear, you can view the remaining ones in this menu as well.
-The alert button will dissapear once all alerts are dismissed.
+The alert button will disappear once all alerts are dismissed.

docs/source/guides/usage.md

@@ -1,66 +1,20 @@
 # Using Robodash
 
-Robodash has two parts: the core, and the toolkit.
+Robodash provides multiple functionalities for different use cases:
 
-- The core library is the system that enables interoperability between templates
-  by providing a view-management system for LVGL. This API requires knowledge of
-  LVGL. Compatible with C and C++.
+- If you would like to learn more about Robodash's suite of built-in widgets,
+  such as the autonomous selector, see the [widgets guide](./usage/widgets.md).
 
-- The toolkit is the set of provided class-based UI tools intended for end users
-  of the library. These require no knowledge of LVGL and require minimal
-  configuration. Only compatible with C++.
+- If you want to integrate your own LVGL GUIs with Robodash, see the
+  [views guide](./usage/views.md).
 
-## Toolkit
+- If you're a template developer looking to depend on Robodash, check out the
+  [template guide](./usage/template.md) as well
 
-All of the tools provided by Robodash are class-based, and are designed to be as
-simple as possible to use. The following example utilizes the autonomous
-selector and the on-screen console.
+```{toctree}
+:hidden:
 
-```cpp
-rd::Selector selector({
-   {"Auton 0", &auton0},
-   {"Auton 1", &simple_auton},
-   {"Skills Run", &skills}
-});
-
-rd::Console console;
-
-void initialize() {
-   console.println("Initializing robot...");
-   // Robot stuff would happen...
-}
-
-void autonomous() {
-   console.println("Running auton...");
-   selector.run_auton();
-}
+./usage/views.md
+./usage/widgets.md
+./usage/template.md
 ```
-
-Documention for each class is linked on the topics page.
-
-## Core
-
-The core library is the view management system for LVGL, and is designed to be
-as familliar as possible to someone already familliar with LVGL. Each view,
-represented by a memory pointer to an `rd_view_t`, exposes an LVGL object the
-size of the view area, which can be thought of as a screen. It is very important
-that any LVGL objects that are created in your template or user program are a
-child of this exposed object, **NOT `lv_scr_act()`**, since robodash manages
-which view is active by hiding and unhiding the object cooresponding to each
-view.
-
-The name passed to each view will be the name that is displayed on screen in the
-view switcher and any alert dialogues spawned by the view.
-
-The following is an example of a simple view that displays a text label.
-
-```cpp
-void opcontrol() {
-   rd_view_t *view = rd_view_create("custom view");
-   lv_label_t *label = lv_label_create(rd_view_obj(view));
-   lv_label_set_text(label, "example");
-   lv_obj_align(label, LV_ALIGN_CENTER, 0, 0);
-}
-```
-
-You can learn more about the core library at the [Core Reference](../api/core.md) page.

docs/source/guides/usage/template.md

@@ -0,0 +1,20 @@
+# Template Integration
+
+When depending on Robodash, it is recommended that you follow these instructions
+for better user ease of use.
+
+- **Do not bundle Robodash with your template** - It is not recommended that you
+  add Robodash's source files to your template and distribute it with your own
+  template. This prevents users from upgrading unless your own template
+  upgrades, and places the burden on you to upgrade your template when Robodash
+  upgrades. For new users, it is recommended instead to have a "starter project"
+  that is pre-configured with Robodash and your own template.
+
+- **Inform users that your template uses Robodash** - You should inform users
+  that your template depends on Robodash so they know to install it.
+  Additionally, provide some form of guidance for installing Robodash (a link to
+  these docs or your own instructions). You should also indicate which version
+  of Robodash your template uses, so users know what versions they can use.
+
+- **Do not modify Robodash** - No modifications should be made to Robodash's
+  header or source files, and no additions should be made to its namespace.

docs/source/guides/usage/views.md

@@ -0,0 +1,30 @@
+## Views
+
+Robodash provides the views API for other LVGL-powered GUIs to plug into its
+view-management system.
+
+Below is an example on creating a view called "my view".
+
+```cpp
+rd_view_t *view = rd_view_create("my view");
+```
+
+Creating a view will return a pointer to an `rd_view_t`, which holds the name of
+the view and the LVGL object for the view. The name passed to the view
+constructor will be the name that is displayed on screen in the view switcher
+and any alert dialogues spawned by the view. The view's LVGL object should
+parent any LVGL UI that is a part of that view, since this is how Robodash
+changes which view is currently active on the screen. **Any instance of
+`lv_scr_act()` in your LVGL GUI code should be replaced with
+`lv_view_obj(your_view)`.**
+
+The following is an example of a simple view that displays a text label.
+
+```cpp
+rd_view_t *view = rd_view_create("custom view");
+lv_label_t *label = lv_label_create(rd_view_obj(view));
+lv_label_set_text(label, "example");
+lv_obj_align(label, LV_ALIGN_CENTER, 0, 0);
+```
+
+[Views API Reference](../../api/core.md) page.

docs/source/guides/usage/widgets.md

@@ -0,0 +1,83 @@
+# Widgets
+
+Robodash provides a suite of simple, commonly used GUI widgets.
+
+## Selector
+
+The [Selector Widget](../../api/views/selector.md) is a function selector
+designed for managing autonomous runs.
+
+To use the selector we can construct it in the global scope of our `main.cpp`
+file.
+
+```cpp
+rd::Selector selector({
+    {"Best auton", best_auton},
+    {"Simple auton", simple_auton},
+    {"Good auton", good_auton},
+});
+```
+
+The selector's constructor takes a vector of pairs that hold a string and a
+function. The string is the name that appears on the display as the function's
+name, and the function is what is called when it is selected.
+
+Our example assumes we have three functions, `best_auton`, `simple_auton`, and
+`good_auton`. These functions should take no arguments and return `void`.
+
+While the selector appears on the screen, we still need to make our selected
+routine run when our bot is in autonomous mode.
+
+In your `main.cpp` file, call `selector.run_auton()` in your `autonomous`
+function.
+
+```cpp
+void autonomous() {
+	selector.run_auton();
+}
+```
+
+Now, when our robot is in autonomous mode, our user-selected routine will run.
+In addition, if an SD card is in the brain, the selected routine will be
+preserved next time the program is run.
+
+## Console
+
+The [Console Widget](../../api/views/console.md) provides a text display for
+quickly and easily displaying information for debugging. To create a console, we
+can construct it in our `main.cpp` file's global scope.
+
+```cpp
+rd::Console console;
+```
+
+We can now log information to the console with `console.print`,
+`console.println`, and `console.printf`, and we can clear the console with
+`console.clear`.
+
+```cpp
+console.println("Hello");
+console.printf("The robot's heading is %f\n", some_imu.get_heading());
+```
+
+## Image
+
+The [Image Widget](../../api/views/image.md) provides a way to display LVGL
+images to the LCD.
+
+Images displayed must be converted with the
+[LVGL image converter](https://lvgl.io/tools/imageconverter) for LVGL 8. You can
+convert the image to a C array and place it in your project's `src` directory,
+or convert it to a a binary file and load it onto a microSD card.
+
+To create an image, we can construct it with a path to an LVGL-converted
+`image.bin` file on a loaded SD card, or to an LVGL image variable. You also
+must pass a name to the image.
+
+```cpp
+// microSD approach
+rd::Image image1("S:/usd/logo.bin", "Team Logo");
+
+// C array approach
+rd::Image image2(team_logo, "Team Logo")
+```

docs/source/index.md

@@ -43,8 +43,8 @@ guides/ui.md
 
 ```{toctree}
 :hidden:
-:caption: API Reference
+:caption: Reference
 
-api/core.md
-api/views/index.md
+api/index.md
+LVGL 8.3 Docs <https://docs.lvgl.io/8.3/>
 ```