Contributing & editing the docs#

HJCD-IK is a batched GPU IK solver built on GRiD (kinematics codegen) and 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 (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 Custom robot (GRiD codegen workflow).

  • 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 The HJCD-IK 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 + the PyData theme, with the C++/CUDA API reference generated by Doxygen and bridged in via Breathe. Narrative pages are Markdown (via MyST) 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#

./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 Examples & 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.