Skip to content

Developers.md

Latest commit

 

History

History
123 lines (95 loc) · 3.31 KB

Developers.md

File metadata and controls

123 lines (95 loc) · 3.31 KB

Requirements management with Poetry

pip install "poetry>=2.0"
poetry install --all-extras --with=dev,docs

(in a virtual environment) to install the requirements.

Please install the pre-commit hooks

pip install pre-commit
pre-commit install

Autoflake for notebooks

`autoflake`` is not officially supported by nbqa because it has some risks: nbQA-dev/nbQA#755 But it can be valuable to run it manually and check the results.

nbqa autoflake --remove-all-unused-imports --in-place .

To Run the Unit Tests

Install the prerequisites:

bash setup/.../install_prereqs.sh

If you have access to the solutions repository (e.g. manipulation-solutions or underactuated-solutions), run e.g.

git clone git@github.com:RobotLocomotion/manipulation-solutions.git solutions
cd solutions && git checkout $(cat ../solutions_sha.txt) && cd ..

Make sure that you have done a recursive checkout in this repository, or have run

git submodule update --init --recursive

Then run

pytest

Updating dependencies

First update the dependency in pyproject.toml.

poetry lock

Then run

poetry install --all-extras --with=dev,docs

to update your virtual environment.

To update the pip wheels

If you make a change to the dependencies or library directory, you will need to update the pip wheels.

  • First PR the code changes, and mark the PR with the requires new pip wheels label.
  • Make sure to git pull your merged PR into master.
  • Once the PR is merged update the version number in pyproject.toml, then git commit that small change, then from the root directory, run:
rm -rf dist/*
poetry publish --build && cd book && ./Deepnote.sh
  • The push to deepnote might update chapters.js; commit those changes now, too.
  • Finally, PR the updated pyproject.toml (without the requires new pip wheels label).

Note: use poetry config pypi-token.pypi <token> once to set up your pypi token.

To update the Docker image (and pip wheels)

It's good form to update the pip wheels first (so that the Docker contains the latest pip dependencies):

rm -rf dist/*
poetry publish --build
./book/Deepnote_docker.sh && cd book && ./Deepnote.sh

And make sure to follow the printed instructions to build the image once on deepnote. Then run a few notebooks on deepnote to convince yourself you haven't broken anything.

Building the documentation

You will need to install sphinx:

poetry install --with docs
pip install sphinx myst-parser sphinx_rtd_theme

From the root directory, run

rm -rf book/python && sphinx-build -M html $(book/htmlbook/book_name.py) /tmp/my_doc && cp -r /tmp/my_doc/html book/python

Note that the website will only install the dependencies in the docs group, so poetry install --only docs must obtain all of the relevant dependencies.

To debug a notebook with a local build of Drake

There are several approaches, but perhaps easiest is to just add a few lines at the top of the notebook:

import sys
import os

python_version = f"python{sys.version_info.major}.{sys.version_info.minor}"
drake_path = os.path.expanduser(f"~/drake-install/lib/{python_version}/site-packages")
if drake_path not in sys.path:
    sys.path.insert(0, drake_path)

import pydrake
print(f"Using pydrake from: {pydrake.__file__}")