Developers.md

Requirements management with Poetry

pip3 install poetry
poetry install --with=dev,docs

(in a virtual environment) to install the requirements.

Please install the pre-commit hooks

pip3 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

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

git submodule update --init --recursive

Then run

bazel test //...

Updating dependencies

Bazel currently uses requirements-bazel.txt, which we generate from poetry

To generate it, run

poetry lock
./book/htmlbook/PoetryExport.sh

Hopefully direct poetry support in bazel will land soon, or I can use rules_python_poetry directly; but it looks like it will still require poetry to fix [their issue](# python-poetry/poetry-plugin-export#176).

To update the pip wheels

Note: This should really only happen when drake publishes new wheels (since I'm testing on drake master, not on the drake release).

Update the version number in pyproject.toml, and the drake version, then from the root directory, run:

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

(Use poetry config pypi-token.pypi <token> once first; the token in saved with my other passwords)

Publishing to Deepnote

cd book
./Deepnote.sh

Building the documentation

You will need to install sphinx:

poetry install --with docs

From the root directory, run

rm -rf book/python && sphinx-build -M html underactuated /tmp/manip_doc && cp -r /tmp/manip_doc/html book/python

Tips for developers

These are things that I often add to my preamble of the notebook (ever since vs code broke my pythonpath importing)

%load_ext autoreload
%autoreload 2
import sys
sys.path.append('/home/russt/drake-install/lib/python3.6/site-packages')
sys.path.append('/home/russt/underactuated')

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__}")