Contributing
============

Contributions are welcome — whether that's firmware improvements, documentation
fixes, or new case designs. The project lives at
`github.com/f321x/offline-bitcoin-atm <https://github.com/f321x/offline-bitcoin-atm>`_.

Firmware
--------

Before opening a pull request, make sure the firmware builds, the host tests pass,
and the linters are happy:

.. code-block:: bash

   cargo build
   cargo test --lib --no-default-features --target x86_64-unknown-linux-gnu
   cargo fmt --all -- --check
   cargo clippy --all-targets --all-features --workspace -- -D warnings

See :doc:`development/building-and-testing` for the full toolchain setup and
:doc:`development/index` for an architecture overview.

Documentation
-------------

These docs are built with `Sphinx <https://www.sphinx-doc.org/>`_ from
reStructuredText sources in the ``docs/`` directory, using the built-in Alabaster
theme (no extra dependencies). The published site lives at
``https://f321x.github.io/offline-bitcoin-atm/docs/``.

Build the docs locally (always in a virtual environment, never a global install):

.. code-block:: bash

   python -m venv .venv
   source .venv/bin/activate
   pip install -r docs/requirements.txt
   sphinx-build -b html docs docs/_build/html
   # open docs/_build/html/index.html in your browser

To catch broken references and other issues the way CI does, build with warnings
treated as errors:

.. code-block:: bash

   sphinx-build -W -b html docs docs/_build/html

The site is published automatically by the ``docs.yml`` GitHub Actions workflow
on every push to ``master`` (and on each release). The same workflow also bundles
the browser-based web flasher at the site root, so there is a single GitHub Pages
deployment for the whole site.