# Contributing & editing the docs

HJCD-IK is a batched GPU IK solver built on [GRiD](https://github.com/A2R-Lab/GRiD) (kinematics codegen)
and [GLASS](https://github.com/A2R-Lab/GLASS) (single-block / warp-scoped CUDA linear algebra). The
canonical contributor entry points are the repository's `CLAUDE.md` (architecture + mental model) and
[the debugging guide](https://github.com/A2R-Lab/HJCD-IK/blob/main/docs/development/agent_debugging_guide.md)
(recurring traps + validation checklist).

## Before you start

- Initialize submodules: `git submodule update --init --recursive`.
- Set up a dev environment (venv, deps, codegen, build, **and the docs toolchain**) with
  `./scripts/setup/setup_dev.sh`.

## Workflow

- Branch from `main`; keep PRs focused. **Short, single-line commit messages; no `Co-Authored-By` footer.**
- Changes that belong upstream — kinematics in **GRiD**, linear algebra in **GLASS** — should be PR'd to
  those repos rather than patched locally. Keep HJCD-IK thin and the dependencies modular.

## Discipline

- **Never hand-edit `csrc/generated/grid.cuh`.** It is GRiD codegen output. Regenerate it with
  `python scripts/codegen/generate_grid.py <urdf> -t <target>` and rebuild — see
  {doc}`../user_guide/tutorials/custom_robot`.
- **Keep the math warp-scoped.** The solver is warp-per-candidate; use warp primitives
  (`__shfl_*_sync` / `__syncwarp`, `grid::ee_pose_inner_warp`, `glass::warp::`), not block-scoped,
  cooperative-groups, or vendor paths. See {doc}`../user_guide/concepts/hjcd_algorithm`.
- **No regressions.** Run `python benchmark/hjcd_ik_bench.py --skip-grid-codegen` before/after kernel
  changes and compare to the committed baseline. Isolate timing runs (no concurrent GPU load).

## Tests

- `pytest tests/` — regression (solved-rate / position–orientation error vs. the committed baseline) plus
  FK-equivalence checks.

## Editing the docs

This site is built with [Sphinx](https://www.sphinx-doc.org/) + the
[PyData theme](https://pydata-sphinx-theme.readthedocs.io/), with the C++/CUDA API reference generated by
[Doxygen](https://www.doxygen.nl/) and bridged in via [Breathe](https://breathe.readthedocs.io/). Narrative
pages are Markdown (via [MyST](https://myst-parser.readthedocs.io/)) or reStructuredText.

```
docs/
  Doxyfile            Doxygen config (XML only; input = ../csrc)
  Makefile            `make all` = doxygen + sphinx-build
  requirements.txt    Sphinx + Breathe + pydata-sphinx-theme + myst + sphinx-design
  source/
    conf.py           Sphinx config (theme, breathe, extensions)
    index.rst         docs landing page (grid cards + toctree)
    _static/          logo, favicon, custom.css, paper/ (committed paper figures)
    user_guide/       getting_started/ · concepts/ · tutorials/ · benchmarks/
    api_reference/    python.rst (hand-written) + kernel/collision.rst (.. doxygenfile::)
    developer_guide/  this section
docs/development/     un-published support docs (agent_debugging_guide, STARTUP_PROMPT)
```

### Build locally

```bash
./scripts/setup/setup_dev.sh        # installs the docs toolchain into .venv (+ doxygen via apt)
source .venv/bin/activate

cd docs && make all                 # docs only → docs/build/html/index.html
#   — or —
./scripts/build_site.sh             # full site → _site/ (landing at /, docs under /docs/)
```

`scripts/build_site.sh` is the **same script CI runs**, so a local build matches the deployed site exactly.

### Conventions

- **C++/CUDA API** is generated from in-source `/** ... */` doc-comments. To document a new public symbol,
  add the doc-comment in the header and ensure its file has a `.. doxygenfile::` entry under
  `api_reference/`. Doxygen runs with `EXTRACT_ALL=NO`, so only documented symbols appear.
- **Python API** (`api_reference/python.rst`) is hand-authored — the compiled `hjcdik` extension is *not*
  imported at build time (CI has no GPU), so keep that page in sync with `csrc/bindings/pybind_module.cpp` by hand.
- **Benchmark figures/tables** are committed static assets under `_static/paper/`, taken from the
  camera-ready paper. Do **not** embed locally-generated benchmark output — see {doc}`../user_guide/benchmarks/results`.

### Deploy

Deployment is **automatic**: any push to `main` touching `docs/**`, `csrc/**`, or
`examples/**` triggers `.github/workflows/gh-pages.yml`, which runs `scripts/build_site.sh` and publishes
`_site/` to GitHub Pages. No manual regeneration — edit, commit to `main`, and the site rebuilds. (Force a
rebuild from the Actions tab via `workflow_dispatch`.) Requirements: **Settings → Pages → Source** must be
**"GitHub Actions"**, and the workflow only runs on `main`.