add bindings and fix documentation

README.md

@@ -18,7 +18,7 @@ disagree is listed under [Divergences](#divergences-from-django).
 
 ## Using it
 
-There is no published package yet, and no language bindings — those are coming. What is here today:
+There is no published package yet, but the language bindings are in place. What is here today:
 
 - **`src/parser.c` and `src/scanner.c` are generated and committed**, so any tree-sitter host can compile
   them directly without running the CLI. The scanner is required: block-name matching
@@ -30,6 +30,38 @@ There is no published package yet, and no language bindings — those are coming
   meant for a linter. See [Queries](#queries).
 - **`tree-sitter.json`** names the grammar `django`, scopes it `source.django`, and points at the query
   files, which is what a tree-sitter host reads to wire all of the above together.
+- **`bindings/`** holds a binding per language, generated by `tree-sitter init` from the `bindings` and
+  `metadata` sections of `tree-sitter.json`. See [Bindings](#bindings).
+
+## Bindings
+
+| Language | Build from a checkout                                    | Entry point                                            |
+| -------- | -------------------------------------------------------- | ------------------------------------------------------ |
+| Node     | `npm install` builds the addon through `node-gyp-build`  | `bindings/node/index.js` (ESM), typed by `index.d.ts`  |
+| Rust     | `cargo build`                                            | `bindings/rust/lib.rs`, `Cargo.toml`                   |
+| Python   | `pip install .`                                          | `bindings/python/tree_sitter_django`, `pyproject.toml` |
+| Go       | `go test ./bindings/go`                                  | `bindings/go/binding.go`, `go.mod`                     |
+| Swift    | `swift build`                                            | `bindings/swift/TreeSitterDjango`, `Package.swift`     |
+| C / C++  | `make` (static, shared and a pkg-config file) or `cmake` | `bindings/c/tree_sitter/tree-sitter-django.h`          |
+
+```js
+import Parser from "tree-sitter";
+import django from "tree-sitter-django";
+
+const parser = new Parser();
+parser.setLanguage(django);
+```
+
+```python
+import tree_sitter, tree_sitter_django
+
+language = tree_sitter.Language(tree_sitter_django.language())
+tree = tree_sitter.Parser(language).parse(b"{% if x %}hi {{ y|upper }}{% endif %}")
+```
+
+The binding files are generated, so they are not edited by hand: change `tree-sitter.json` and re-run
+`tree-sitter init`. `package.json` still carries `"private": true`, so nothing is published from this
+repository yet.
 
 ## Development