docs: improve docstrings

And use Sphinx to generate HTML docs

.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+indent_size = 2
+
+[*.rst]
+indent_size = 3
+
+[*.{c,h,py}]
+indent_size = 4
+max_line_length = 100

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Docs
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - tree_sitter/**
+      - docs/**
+
+concurrency:
+  group: ${{github.workflow}}-${{github.ref}}
+  cancel-in-progress: true
+
+permissions:
+  pages: write
+  id-token: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{steps.deploy.outputs.page_url}}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: pip install -e .[docs]
+        env:
+          CFLAGS: "-O0 -g"
+      - name: Build docs
+        run: sphinx-build -M html docs docs/_build
+      - name: Upload docs artifact
+        uses: actions/deploy-pages@v3
+        with:
+          path: docs/_build/html
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

.gitignore

@@ -7,3 +7,4 @@ dist
 *.so
 __pycache__
 wheelhouse
+docs/_build

README.md

@@ -2,6 +2,7 @@
 
 [![CI][ci]](https://github.com/tree-sitter/py-tree-sitter/actions/workflows/ci.yml)
 [![pypi][pypi]](https://pypi.org/project/tree-sitter/)
+[![docs][docs]](https://tree-sitter.github.io/py-tree-sitter/)
 
 This module provides Python bindings to the [tree-sitter] parsing library.
 
@@ -35,45 +36,7 @@ Then, you can load it as a `Language` object:
 import tree_sitter_python as tspython
 from tree_sitter import Language, Parser
 
-PY_LANGUAGE = Language(tspython.language(), "python")
-```
-
-#### Build from source
-
-> [!WARNING]
-> This method of loading languages is deprecated and will be removed in `v0.22.0`.
-> You should only use it if you need languages that have not updated their bindings.
-> Keep in mind that you will need a C compiler in this case.
-
-First you'll need a Tree-sitter language implementation for each language that you want to parse.
-
-```sh
-git clone https://github.com/tree-sitter/tree-sitter-go
-git clone https://github.com/tree-sitter/tree-sitter-javascript
-git clone https://github.com/tree-sitter/tree-sitter-python
-```
-
-Use the `Language.build_library` method to compile these into a library that's
-usable from Python. This function will return immediately if the library has
-already been compiled since the last time its source code was modified:
-
-```python
-from tree_sitter import Language, Parser
-
-Language.build_library(
-    # Store the library in the `build` directory
-    "build/my-languages.so",
-    # Include one or more languages
-    ["vendor/tree-sitter-go", "vendor/tree-sitter-javascript", "vendor/tree-sitter-python"],
-)
-```
-
-Load the languages into your app as `Language` objects:
-
-```python
-GO_LANGUAGE = Language("build/my-languages.so", "go")
-JS_LANGUAGE = Language("build/my-languages.so", "javascript")
-PY_LANGUAGE = Language("build/my-languages.so", "python")
+PY_LANGUAGE = Language(tspython.language())
 ```
 
 ### Basic parsing
@@ -324,5 +287,6 @@ To try out and explore the code referenced in this README, check out [examples/u
 [tree query]: https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax
 [ci]: https://img.shields.io/github/actions/workflow/status/tree-sitter/py-tree-sitter/ci.yml?logo=github&label=CI
 [pypi]: https://img.shields.io/pypi/v/tree-sitter?logo=pypi&logoColor=ffd242&label=PyPI
+[docs]: https://img.shields.io/github/deployments/tree-sitter/py-tree-sitter/github-pages?logo=sphinx&label=Docs
 [examples/walk_tree.py]: https://github.com/tree-sitter/py-tree-sitter/blob/master/examples/walk_tree.py
 [examples/usage.py]: https://github.com/tree-sitter/py-tree-sitter/blob/master/examples/usage.py

docs/classes/tree_sitter.Language.rst

@@ -0,0 +1,53 @@
+Language
+========
+
+.. autoclass:: tree_sitter.Language
+
+   .. versionchanged:: 0.22.0
+
+      No longer accepts a ``name`` parameter.
+
+
+   Methods
+   -------
+
+   .. automethod:: field_id_for_name
+   .. automethod:: field_name_for_id
+   .. automethod:: id_for_node_kind
+   .. automethod:: lookahead_iterator
+   .. automethod:: next_state
+   .. automethod:: node_kind_for_id
+   .. automethod:: node_kind_is_named
+   .. automethod:: node_kind_is_visible
+   .. automethod:: query
+
+   Special Methods
+   ---------------
+
+   .. automethod:: __eq__
+
+      .. versionadded:: 0.22.0
+   .. automethod:: __hash__
+
+      .. versionadded:: 0.22.0
+   .. automethod:: __index__
+
+      .. versionadded:: 0.22.0
+   .. automethod:: __int__
+
+      .. versionadded:: 0.22.0
+   .. automethod:: __ne__
+
+      .. versionadded:: 0.22.0
+   .. automethod:: __repr__
+
+      .. versionadded:: 0.22.0
+
+
+   Properties
+   ----------
+
+   .. autoattribute:: field_count
+   .. autoattribute:: node_kind_count
+   .. autoattribute:: parse_state_count
+   .. autoattribute:: version

docs/classes/tree_sitter.LookaheadIterator.rst

@@ -0,0 +1,24 @@
+LookaheadIterator
+=================
+
+.. autoclass:: tree_sitter.LookaheadIterator
+
+   Methods
+   -------
+
+   .. automethod:: iter_names
+   .. automethod:: reset
+   .. automethod:: reset_state
+
+   Special methods
+   ---------------
+
+   .. automethod:: __iter__
+   .. automethod:: __next__
+
+   Attributes
+   ----------
+
+   .. autoattribute:: current_symbol
+   .. autoattribute:: current_symbol_name
+   .. autoattribute:: language

docs/classes/tree_sitter.Node.rst

@@ -0,0 +1,65 @@
+Node
+====
+
+.. autoclass:: tree_sitter.Node
+
+   Methods
+   -------
+
+   .. automethod:: child
+   .. automethod:: child_by_field_id
+   .. automethod:: child_by_field_name
+   .. automethod:: children_by_field_id
+   .. automethod:: children_by_field_name
+   .. automethod:: descendant_for_byte_range
+   .. automethod:: descendant_for_point_range
+   .. automethod:: edit
+   .. automethod:: field_name_for_child
+   .. automethod:: named_child
+   .. automethod:: named_descendant_for_byte_range
+   .. automethod:: named_descendant_for_point_range
+   .. automethod:: sexp
+   .. automethod:: walk
+
+   Special Methods
+   ---------------
+
+   .. automethod:: __eq__
+   .. automethod:: __hash__
+   .. automethod:: __ne__
+   .. automethod:: __repr__
+   .. automethod:: __str__
+
+   Attributes
+   ----------
+
+   .. autoattribute:: byte_range
+   .. autoattribute:: child_count
+   .. autoattribute:: children
+   .. autoattribute:: descendant_count
+   .. autoattribute:: end_byte
+   .. autoattribute:: end_point
+   .. autoattribute:: grammar_id
+   .. autoattribute:: grammar_name
+   .. autoattribute:: has_changes
+   .. autoattribute:: has_error
+   .. autoattribute:: id
+   .. autoattribute:: is_error
+   .. autoattribute:: is_extra
+   .. autoattribute:: is_missing
+   .. autoattribute:: is_named
+   .. autoattribute:: kind_id
+   .. autoattribute:: named_child_count
+   .. autoattribute:: named_children
+   .. autoattribute:: next_named_sibling
+   .. autoattribute:: next_parse_state
+   .. autoattribute:: next_sibling
+   .. autoattribute:: parent
+   .. autoattribute:: parse_state
+   .. autoattribute:: prev_named_sibling
+   .. autoattribute:: prev_sibling
+   .. autoattribute:: range
+   .. autoattribute:: start_byte
+   .. autoattribute:: start_point
+   .. autoattribute:: text
+   .. autoattribute:: type

docs/classes/tree_sitter.Parser.rst

@@ -0,0 +1,31 @@
+Parser
+======
+
+.. autoclass:: tree_sitter.Parser
+
+   .. versionadded:: 0.22.0
+
+      constructor
+
+   Methods
+   -------
+
+
+   .. automethod:: parse
+   .. automethod:: reset
+   .. automethod:: set_included_ranges
+   .. automethod:: set_language
+   .. automethod:: set_timeout_micros
+
+   Attributes
+   ----------
+
+   .. autoattribute:: included_ranges
+
+      .. versionadded:: 0.22.0
+   .. autoattribute:: language
+
+      .. versionadded:: 0.22.0
+   .. autoattribute:: timeout_micros
+
+      .. versionadded:: 0.22.0

docs/classes/tree_sitter.Point.rst

@@ -0,0 +1,10 @@
+Point
+=====
+
+.. autoclass:: tree_sitter.Point
+
+   Attributes
+   ----------
+
+   .. autoattribute:: column
+   .. autoattribute:: row

docs/classes/tree_sitter.Query.rst

@@ -0,0 +1,14 @@
+Query
+=====
+
+.. autoclass:: tree_sitter.Query
+
+   .. versionadded:: 0.22.0
+
+      constructor
+
+   Methods
+   -------
+
+   .. automethod:: captures
+   .. automethod:: matches

docs/classes/tree_sitter.Range.rst

@@ -0,0 +1,22 @@
+Range
+=====
+
+.. autoclass:: tree_sitter.Range
+
+   Special Methods
+   ---------------
+
+   .. automethod:: __eq__
+   .. automethod:: __ne__
+   .. automethod:: __repr__
+   .. automethod:: __hash__
+
+      .. versionadded:: 0.22.0
+
+   Attributes
+   ----------
+
+   .. autoattribute:: end_byte
+   .. autoattribute:: end_point
+   .. autoattribute:: start_byte
+   .. autoattribute:: start_point

docs/classes/tree_sitter.Tree.rst

@@ -0,0 +1,19 @@
+Tree
+====
+
+.. autoclass:: tree_sitter.Tree
+
+   Methods
+   -------
+
+   .. automethod:: changed_ranges
+   .. automethod:: edit
+   .. automethod:: root_node_with_offset
+   .. automethod:: walk
+
+   Attributes
+   ----------
+
+   .. autoattribute:: included_ranges
+   .. autoattribute:: root_node
+   .. autoattribute:: text