very rough docs with development instructions

docs/source/development.md

@@ -1,3 +1,42 @@
 # Development
 
-TODO: fill once dev pipeline is fully set up.
+## Overview
+We use the following tools for development:
+* Docker and Docker Compose for isolating system states and for development containers
+* [`pixi`](https://pixi.sh/latest/) for package-level dependency management across platforms
+* [`ruff`](https://docs.astral.sh/ruff/) and [`pyright`](https://github.com/microsoft/pyright) for linting, code-style enforcement, and type checking of Python code
+* [`clang-tidy`](https://clang.llvm.org/extra/clang-tidy/) and [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) for C++ code
+* [`pre-commit`](https://pre-commit.com/) for registering code checks as commit hooks
+* [`pytest`](https://docs.pytest.org/en/8.2.x/) for python code tests
+
+We ensure that all code checks pass in a CI workflow before allowing PRs to merge into `main`.
+
+## Getting Started
+First, there are local dependencies required to use our development pipeline. Run the following script from the repo root:
+```
+source dev_setup.sh
+newgrp docker
+```
+This will install `docker`, `nvidia-container-toolkit`, `pixi`, `uv`, and `nvm` (required for `pyright`). It also sets the `OBELISK_ROOT` environment variable to the path of the repository root on your local filesystem.
+
+Optionally, to build the development Docker container, run from the repo root:
+```
+docker compose -f docker/docker-compose.yml run --build obelisk
+```
+To enter the container without rebuilding or to join from a different terminal window, run
+```
+docker compose -f docker/docker-compose.yml run obelisk
+```
+If you are running on a machine with no Nvidia GPUs, you can instead run
+```
+docker compose -f docker/docker-compose-no-gpu.yml run --build obelisk
+```
+If your IDE supports it, you can instead use the provided `.devcontainer` to launch this container. Either way, your repository root will be mounted into the container at the exact same file location, your username, user ID, and group ID will be shared with the container, and you can freely run `sudo` without supplying a password for any command.
+
+Once ready for development, you should start the `pixi` shell, which is like activating a `conda` environment (but `pixi` environments are project/directory-specific, not shell-wide). To do this, run in the repo root:
+```
+pixi shell --environment dev
+```
+The environment `dev` contains the most critical development dependencies. However, you can view the available environment sets in the `pixi.toml` to start a different environment if you would like. For example, if you are only updating the docs, you can do this by setting the environment flag to `docs`.
+
+While in the `pixi` shell and/or Docker container, all changes made in the repository or to the `~/.bashrc` file persist in your local file system. You can also use `git` with no issue to push changes.

docs/source/getting_started.md

@@ -1,14 +1,30 @@
 # Getting Started
-All instructions in this section assume you are using Ubuntu 22.04. The development dependencies should be installed when `dev_setup.sh` is run from the repository root.
+All instructions in this section assume you are using Ubuntu 22.04. The development dependencies should be installed when `source dev_setup.sh` is run from the repository root.
 
-## Using Docker
-We highly recommend using `docker` to containerize our code. This provides consistent environments and makes it easy to share code with others.
+There are two options for using `obelisk`. One is to use the same dependency management and containerization tools used for development to ensure reproducibility. The other is to simply install `obelisk` as a dependency of your project without using these tools. We will explain how to do both here.
 
-To build a minimal Docker image with only barebones ROS dependencies, run the following command from the `docker` directory:
+## Option 1: Isolation
+TODO(ahl): look this over and verify how to use isolation to do dependency management. Update docs in a separate PR.
+<!-- Once you have cloned this repository, you can run in the repo root:
 ```
-docker image build -t <image_name> -f Dockerfile.minimal .
+docker compose -f docker/docker-compose.yml run --build obelisk
 ```
-To enter the build container, run the following command in the repository root:
+This will load a Docker container with the repository root mounted into the container.
+
+If your downstream package is managed with `pixi`, you can install `obelisk` by [specifying the link to this repository](https://pixi.sh/latest/reference/project_configuration/#version-specification) in your `pixi.toml` file. -->
+
+## Option 2: Quick Installation
+To install the `obelisk` ROS2 packages, if you have installed `pixi`, you can run
+```
+pixi run source_obelisk --environment ros2-install
 ```
-bash startup.sh -n <image_name>
+This will allow you to use the packages in the `obelisk_ws` directory as an underlay for your own ROS2 packages.
+
+Similarly, you can instead run in the `obelisk_ws` directory
+```
+colcon build --symlink-install
+echo "source install/setup.sh" >> ~/.bashrc
 ```
+to build our packages and manually install them as an underlay.
+
+TODO(ahl): when the `obelisk_py` and `obelisk_cpp` packages have content, include instructions for how to install them as well.

pixi.toml

@@ -142,6 +142,9 @@ torch121 = { features=["cuda121", "torch121"] }
 test-workflow = { features=["test", "dev"] }
 test = { features=["cuda121", "torch121", "ros2base", "test"], solve-group="dev" }
 
+# ros2
+ros2-install = { features=["ros2base"] }
+
 # dev
 dev = { features=["cuda121", "torch121", "ros2base", "test", "dev"], solve-group="dev" }
 docs = { features=["docs"] }