treeherder/docs/common_tasks.md

Common tasks

Serving the docs locally

The docs are built using MkDocs, which has a live-reloading development server, that makes working on the docs locally much easier.

% pip install poetry
% poetry run mkdocs serve

!!! note On Windows you might need to fallback python -m venv venv or virtualenv to manage your virtualenv if poetry does not work for you.

The docs will then be available at: http://localhost:8000

Updating package.json

• Always use yarn to make changes, not npm, so that yarn.lock remains in sync.
• Add new packages using yarn add <PACKAGE> (yarn.lock will be automatically updated).
• After changes to package.json use yarn install to install them and automatically update yarn.lock.
• For more details see the Yarn documentation.

Debugging Tools

You can use the Python Debugger (pdb) in a Docker container. After starting a local Treeherder instance using docker-compose, in a separate shell type docker attach backend. Then set a breakpoint in your file using either import pdb; pdb.set_trace() or breakpoint() (for Python v3.7+). The pdb debugger will start in that shell once the breakpoint has been triggered. For example, it can be triggered via refreshing the browser (localhost) if the view you're on calls an API with a breakpoint on it.