Contributing

Dev setup

git clone https://github.com/netstim/BrainDeer.git
cd BrainDeer
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Before every commit:

ruff check . && ruff format .
mypy src
pytest

Building the docs

Install the docs toolchain (MkDocs Material + Sphinx):

pip install -e ".[docs]"

Command

Result

mkdocs serve

User docs + Sphinx merged at /dev/ via docs_hooks.py

./scripts/build_docs.sh

One-shot mkdocs build into site/

make -C sphinx dirhtml

Sphinx only → sphinx/_build/dirhtml

Local URLs (default MkDocs port):

  • User docs: http://127.0.0.1:8000/BrainDeer/

  • Developer docs: http://127.0.0.1:8000/BrainDeer/dev/

Media conventions (user docs / MkDocs)

These apply to pages under docs/ (Material for MkDocs), not to Sphinx MyST pages:

  • Screenshots → docs/assets/img/, consistent window size

  • Videos → prefer YouTube/Vimeo embeds; short clips in docs/assets/video/

  • Responsive embeds use the wrapper from docs/stylesheets/extra.css:

<div class="video-container">
  <iframe src="https://www.youtube.com/embed/VIDEO_ID" allowfullscreen></iframe>
</div>

  • Mark open media tasks in MkDocs pages with an admonition, for example !!! tip "Media for this page", so gaps stay visible in the user guide.

Sphinx pages use MyST admonitions (:::{note}, :::{tip}, …) instead.

Commit conventions

Short, tag-prefixed messages: ADD:, UPD:, FIX:, REF:, DOC:, TST: — e.g. DOC: warpdrive guide.