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 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..f21002f7d --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,169 @@ +# 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. + +## 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. + +## 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`]. + +## 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 + +## 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/ +[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/ +[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 +[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/ +[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 +[`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