From 4b688d5bbe026226fa9f52d2093902cc072b0c25 Mon Sep 17 00:00:00 2001 From: Jacob Koziej Date: Sat, 27 Jan 2024 18:10:40 -0500 Subject: [PATCH 1/8] Add `getting-started.md` --- docs/SUMMARY.md | 4 ++++ docs/getting-started.md | 1 + 2 files changed, 5 insertions(+) create mode 100644 docs/getting-started.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index f48122b6a..1a80aa771 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -4,6 +4,10 @@ ______________________________________________________________________ +- [Getting Started](getting-started.md) + +______________________________________________________________________ + # About - [Contributing](contributing.md) diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 000000000..bad55622f --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1 @@ +# Getting Started From 0aff6276c420e899392ca082cd8e8e828956a70d Mon Sep 17 00:00:00 2001 From: Jacob Koziej Date: Sat, 27 Jan 2024 18:12:10 -0500 Subject: [PATCH 2/8] Add introductory blurb --- docs/getting-started.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index bad55622f..2720d315e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1 +1,10 @@ # Getting Started + +[`selfdrive`] is a rather *complicated* repo. + +If you've never worked on a project of this scale, it can be daunting to +know where to start. The goal of this guide is to give you enough of a +foothold to start asking the right questions and to begin your adventure +here at Autonomy Lab. + +[`selfdrive`]: https://github.com/CooperUnion/selfdrive From 7d8b1eafa60cd3001d4a071de6cba3f372ca9d8a Mon Sep 17 00:00:00 2001 From: Jacob Koziej Date: Mon, 29 Jan 2024 19:03:01 -0500 Subject: [PATCH 3/8] Add `Fundamentals` --- docs/getting-started.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index 2720d315e..9364ec3d8 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -7,4 +7,45 @@ know where to start. The goal of this guide is to give you enough of a foothold to start asking the right questions and to begin your adventure here at Autonomy Lab. +## Fundamentals + +Before we even get to cloning [`selfdrive`], you need to have the basic +mechanical skills required to traverse a shell. [MIT's Missing Semester] +serves as a great starting point for just this. The following table +lists the lectures you should watch if you plan to work on a specific +Autonomy Lab group: + +| Lecture | Hardware | Firmware | Algorithms | +| ----------------------------- | -------- | -------- | ---------- | +| [Course overview + the shell] | ✓\* | ✓\* | ✓\* | +| [Shell Tools and Scripting] | ✓ | ✓\* | ✓\* | +| [Editors (Vim)] | | | | +| [Data Wrangling] | | ✓ | ✓\* | +| [Command-line Environment] | ✓ | ✓\* | ✓\* | +| [Version Control (Git)] | ✓\* | ✓\* | ✓\* | +| [Debugging and Profiling] | | ✓ | ✓ | +| [Metaprogramming] | | ✓ | ✓ | +| [Security and Cryptography] | | | | +| [Potpourri] | | ✓ | ✓ | +| [Q&A] | | ✓ | ✓ | + +> *Note: an `*` denotes you should also do the associated exercises.* + +At a minimum, to clone [`selfdrive`], you should watch and do the +exercises for [Course overview + the shell] and [Version Control (Git)], +as these lectures provide you the fundamentals to hit the ground +running. + +[command-line environment]: https://missing.csail.mit.edu/2020/command-line/ +[course overview + the shell]: https://missing.csail.mit.edu/2020/course-shell/ +[data wrangling]: https://missing.csail.mit.edu/2020/data-wrangling/ +[debugging and profiling]: https://missing.csail.mit.edu/2020/debugging-profiling/ +[editors (vim)]: https://missing.csail.mit.edu/2020/editors/ +[metaprogramming]: https://missing.csail.mit.edu/2020/metaprogramming/ +[mit's missing semester]: https://missing.csail.mit.edu/ +[potpourri]: https://missing.csail.mit.edu/2020/potpourri/ +[q&a]: https://missing.csail.mit.edu/2020/qa/ +[security and cryptography]: https://missing.csail.mit.edu/2020/security/ +[shell tools and scripting]: https://missing.csail.mit.edu/2020/shell-tools/ +[version control (git)]: https://missing.csail.mit.edu/2020/version-control/ [`selfdrive`]: https://github.com/CooperUnion/selfdrive From a60babdea42570fd8284c8cb7c0e7609a3a583a7 Mon Sep 17 00:00:00 2001 From: Jacob Koziej Date: Mon, 29 Jan 2024 19:12:06 -0500 Subject: [PATCH 4/8] Add `System Configuration` --- docs/getting-started.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index 9364ec3d8..542f0e9b0 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -36,16 +36,27 @@ exercises for [Course overview + the shell] and [Version Control (Git)], as these lectures provide you the fundamentals to hit the ground running. +## System Configuration + +Since [`selfdrive`] consists of software written in different +programming languages with a wide variety of dependencies, we've made an +effort to make getting your machine ready as painless as possible with +the [Nix package manager] and [direnv]. You can find cloning +instructions and system setup information on the repo's [`README.md`]. + [command-line environment]: https://missing.csail.mit.edu/2020/command-line/ [course overview + the shell]: https://missing.csail.mit.edu/2020/course-shell/ [data wrangling]: https://missing.csail.mit.edu/2020/data-wrangling/ [debugging and profiling]: https://missing.csail.mit.edu/2020/debugging-profiling/ +[direnv]: https://direnv.net/ [editors (vim)]: https://missing.csail.mit.edu/2020/editors/ [metaprogramming]: https://missing.csail.mit.edu/2020/metaprogramming/ [mit's missing semester]: https://missing.csail.mit.edu/ +[nix package manager]: https://nixos.org/ [potpourri]: https://missing.csail.mit.edu/2020/potpourri/ [q&a]: https://missing.csail.mit.edu/2020/qa/ [security and cryptography]: https://missing.csail.mit.edu/2020/security/ [shell tools and scripting]: https://missing.csail.mit.edu/2020/shell-tools/ [version control (git)]: https://missing.csail.mit.edu/2020/version-control/ +[`readme.md`]: https://github.com/CooperUnion/selfdrive/blob/dev/README.md [`selfdrive`]: https://github.com/CooperUnion/selfdrive From cb86653f8d50138cc4332cfc0ed1ca6b66b8991b Mon Sep 17 00:00:00 2001 From: Jacob Koziej Date: Mon, 29 Jan 2024 20:42:40 -0500 Subject: [PATCH 5/8] Add `Repo Layout` --- docs/getting-started.md | 98 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index 542f0e9b0..742f83bf3 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -44,7 +44,96 @@ effort to make getting your machine ready as painless as possible with the [Nix package manager] and [direnv]. You can find cloning instructions and system setup information on the repo's [`README.md`]. +## Repo Layout + +> Currently, [`selfdrive`] does not respect this structure. We're in the +> process of migrating over to this layout. Sorry for the time being. + +``` +selfdrive/ ++-- docs/ +| ++-- components/ +| +-- component/ +| |   +-- docs/ +| |   +-- src/ +| |   +-- component.yml +| | +| +-- ... +| ++-- lib/ +| ++-- projects/ +| +-- project/ +| |   +-- docs/ +| |   +-- project.yml +| | +| +-- ... +| ++-- can.yml +| ++-- ... +``` + +There's quite a bit to unpack here, so let's get to it! + +### [`components/`] + +The [`components/`] directory contains components that serve as the +building blocks of a project. + +Each component has a `docs/` directory that contains symlinks to +relevant documentation. These symlinks need to stay up to date as they +will automatically get triggered for manual review on pull requests to +ensure that documentation stays up to date. Having these symlinks also +ensures that anyone who wishes to get up to speed on a component has a +quick list of relevant documentation to read. + +The `src` directory contains the source files. The contents and layout +of this directory highly depend on the component language(s) and use +case. It is best to see existing components to get a feel for it. + +Finally, `component.yml` contains metadata related to the component. + +### [`docs/`] + +The [contributing guidelines] cover the structure for documentation. You +may notice that it closely follows the structure of [`selfdrive`] +itself. + +### [`lib/`] + +The [`lib/`] directory contains shared libraries used in components. +Since these are generalized pieces of software, the contents of each +directory can wildly vary. Feel free to explore these directories if +you're curious. + +### [`projects/`] + +The [`projects/`] directory contains projects that are composed of +various components. Like a component, each project has a `docs/` +directory with symlinks to relevant documentation and a `project.yml` +with related metadata. + +### [`can.yml`] + +[`can.yml`] describes the CAN networks of our projects. Here, you'll +find definitions for networks, messages, and signals for [OpenCAN] to +process. + +### What About Everything Else? + +It'd be impractical to cover every last file and directory in +[`selfdrive`]. Unfortunately, there's no shortcut to knowing where you +can find everything or how various bits of code interact, but there are +tools that can help! + +- [`fd`]: a simple, fast and user-friendly alternative to `find` +- [`fzf`]: a command-line fuzzy finder +- [`rg`]: ripgrep recursively searches directories for a regex pattern + [command-line environment]: https://missing.csail.mit.edu/2020/command-line/ +[contributing guidelines]: contributing.md#directory-structure [course overview + the shell]: https://missing.csail.mit.edu/2020/course-shell/ [data wrangling]: https://missing.csail.mit.edu/2020/data-wrangling/ [debugging and profiling]: https://missing.csail.mit.edu/2020/debugging-profiling/ @@ -53,10 +142,19 @@ instructions and system setup information on the repo's [`README.md`]. [metaprogramming]: https://missing.csail.mit.edu/2020/metaprogramming/ [mit's missing semester]: https://missing.csail.mit.edu/ [nix package manager]: https://nixos.org/ +[opencan]: https://github.com/opencan [potpourri]: https://missing.csail.mit.edu/2020/potpourri/ [q&a]: https://missing.csail.mit.edu/2020/qa/ [security and cryptography]: https://missing.csail.mit.edu/2020/security/ [shell tools and scripting]: https://missing.csail.mit.edu/2020/shell-tools/ [version control (git)]: https://missing.csail.mit.edu/2020/version-control/ +[`can.yml`]: https://github.com/CooperUnion/selfdrive/blob/dev/can.yml +[`components/`]: https://github.com/CooperUnion/selfdrive/tree/dev/components +[`docs/`]: https://github.com/CooperUnion/selfdrive/tree/dev/docs +[`fd`]: https://github.com/sharkdp/fd +[`fzf`]: https://github.com/junegunn/fzf +[`lib/`]: https://github.com/CooperUnion/selfdrive/tree/dev/lib +[`projects/`]: https://github.com/CooperUnion/selfdrive/tree/dev/projects [`readme.md`]: https://github.com/CooperUnion/selfdrive/blob/dev/README.md +[`rg`]: https://github.com/BurntSushi/ripgrep [`selfdrive`]: https://github.com/CooperUnion/selfdrive From f28dfe32f7ce5fb7351969d56f7206430e58305b Mon Sep 17 00:00:00 2001 From: Jacob Koziej Date: Mon, 29 Jan 2024 20:54:46 -0500 Subject: [PATCH 6/8] Add `So What's Next?` --- docs/getting-started.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index 742f83bf3..27d55effd 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -132,6 +132,13 @@ tools that can help! - [`fzf`]: a command-line fuzzy finder - [`rg`]: ripgrep recursively searches directories for a regex pattern +## So What's Next? + +Now that you have a general idea of how [`selfdrive`] works, it's time +to move on to group-specific getting started guides. Feel free to move +along to these without finishing all of the suggested [missing semester] +lectures; however, understand they do nothing but benefit you! + [command-line environment]: https://missing.csail.mit.edu/2020/command-line/ [contributing guidelines]: contributing.md#directory-structure [course overview + the shell]: https://missing.csail.mit.edu/2020/course-shell/ @@ -140,6 +147,7 @@ tools that can help! [direnv]: https://direnv.net/ [editors (vim)]: https://missing.csail.mit.edu/2020/editors/ [metaprogramming]: https://missing.csail.mit.edu/2020/metaprogramming/ +[missing semester]: https://missing.csail.mit.edu/ [mit's missing semester]: https://missing.csail.mit.edu/ [nix package manager]: https://nixos.org/ [opencan]: https://github.com/opencan From e619b9d23fac8528dc67c95bc77f7ddd6bf6020b Mon Sep 17 00:00:00 2001 From: Jacob Koziej Date: Mon, 29 Jan 2024 21:09:17 -0500 Subject: [PATCH 7/8] Enable folding in the navigation sidebar --- book.toml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/book.toml b/book.toml index b0ed1f08c..bc1678352 100644 --- a/book.toml +++ b/book.toml @@ -11,3 +11,6 @@ build-dir = 'build/docs' mathjax-support = true no-section-label = true git-repository-url = 'https://github.com/CooperUnion/selfdrive' + +[output.html.fold] +enable = true From 9686251fdfac53bcc46a9a2bd7238bc51ceadef8 Mon Sep 17 00:00:00 2001 From: Jacob Koziej Date: Thu, 1 Feb 2024 15:12:57 -0500 Subject: [PATCH 8/8] Add link to symlink information --- docs/getting-started.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 27d55effd..f21002f7d 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -82,7 +82,7 @@ There's quite a bit to unpack here, so let's get to it! The [`components/`] directory contains components that serve as the building blocks of a project. -Each component has a `docs/` directory that contains symlinks to +Each component has a `docs/` directory that contains [symlinks] to relevant documentation. These symlinks need to stay up to date as they will automatically get triggered for manual review on pull requests to ensure that documentation stays up to date. Having these symlinks also @@ -155,6 +155,7 @@ lectures; however, understand they do nothing but benefit you! [q&a]: https://missing.csail.mit.edu/2020/qa/ [security and cryptography]: https://missing.csail.mit.edu/2020/security/ [shell tools and scripting]: https://missing.csail.mit.edu/2020/shell-tools/ +[symlinks]: https://en.wikipedia.org/wiki/Symbolic_link [version control (git)]: https://missing.csail.mit.edu/2020/version-control/ [`can.yml`]: https://github.com/CooperUnion/selfdrive/blob/dev/can.yml [`components/`]: https://github.com/CooperUnion/selfdrive/tree/dev/components