Transition to use sphinx with myst

.github/workflows/deploy-docs.yml

@@ -0,0 +1,85 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{
+    github.event_name == 'pull_request'
+    && format('pr-{0}', github.event.number)
+    || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y software-properties-common
+          sudo add-apt-repository universe
+          sudo apt-get update
+          sudo apt-get install -y \
+            cmake \
+            g++ \
+            pkg-config \
+            zlib1g-dev \
+            libeigen3-dev \
+            libzip-dev \
+            zipcmp \
+            zipmerge \
+            ziptool \
+            ninja-build \
+            doxygen
+
+      - name: Install Python dependencies
+        run: python3 -m pip install -r docs/requirements.txt
+
+      - name: Configure trx-cpp
+        run: |
+          cmake -S . -B build \
+            -G Ninja \
+            -DTRX_BUILD_DOCS=ON \
+            -DTRX_BUILD_TESTS=ON \
+            -DTRX_BUILD_EXAMPLES=ON \
+            -DTRX_ENABLE_NIFTI=ON \
+            -DGTest_DIR=${GITHUB_WORKSPACE}/deps/googletest/install/lib/cmake/GTest \
+            -DCMAKE_BUILD_TYPE=Debug \
+            -DCMAKE_C_FLAGS="--coverage" \
+            -DCMAKE_CXX_FLAGS="--coverage"
+
+      - name: Build docs
+        run: |
+          cmake --build build --target docs
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          name: ${{ github.event_name == 'pull_request'
+            && format('github-pages-preview-{0}', github.event.number)
+            || 'github-pages' }}
+          path: docs/_build/html
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

README.md

@@ -1,6 +1,6 @@
 # TRX-cpp
 
-[![Documentation](https://readthedocs.org/projects/trx-cpp/badge/?version=latest)](https://trx-cpp.readthedocs.io/en/latest/)
+[![Docs](https://img.shields.io/badge/docs-github.io-blue?style=flat&logo=github)](https://tee-ar-ex.github.io/trx-cpp/)
 [![codecov](https://codecov.io/gh/tee-ar-ex/trx-cpp/branch/main/graph/badge.svg)](https://codecov.io/gh/tee-ar-ex/trx-cpp)
 
 A C++17 library for reading, writing, and memory-mapping the [TRX tractography format](https://github.com/tee-ar-ex/trx-spec) — efficient storage for large-scale tractography data.
@@ -39,11 +39,11 @@ auto positions = trx.positions.as_matrix<float>(); // (NB_VERTICES, 3)
 trx.close();
 ```
 
-See [Building](https://trx-cpp.readthedocs.io/en/latest/building.html) for platform-specific dependency installation and [Quick Start](https://trx-cpp.readthedocs.io/en/latest/quick_start.html) for a complete first program.
+See [Building](https://tee-ar-ex.github.io/trx-cpp/building.html) for platform-specific dependency installation and [Quick Start](https://tee-ar-ex.github.io/trx-cpp/quick_start.html) for a complete first program.
 
 ## Documentation
 
-Full documentation is at **[trx-cpp.readthedocs.io](https://trx-cpp.readthedocs.io/en/latest/)**.
+Full documentation is at **[tee-ar-ex.github.io/trx-cpp](https://tee-ar-ex.github.io/trx-cpp/)**.
 
 ## Third-party notices
 

docs/api_layers.md

@@ -0,0 +1,73 @@
+# API Layers
+
+trx-cpp provides three complementary interfaces. Understanding when to use
+each one avoids boilerplate and makes code easier to reason about.
+
+## AnyTrxFile — runtime-typed
+
+{class}`trx::AnyTrxFile` is the simplest entry point. It reads the positions
+dtype directly from the file and exposes all arrays as {class}`trx::TypedArray`
+objects with a `dtype` string field. Use this when you only have a file path
+and do not need to perform arithmetic on positions at the C++ type level.
+
+```cpp
+auto trx = trx::load_any("tracks.trx");
+
+std::cout << trx.positions.dtype << "\n";     // e.g. "float16"
+std::cout << trx.num_streamlines() << "\n";
+
+// Access positions as any floating-point type you choose.
+auto pos = trx.positions.as_matrix<float>();  // (NB_VERTICES, 3)
+
+trx.close();
+```
+
+## TrxFile\<DT> — compile-time typed
+
+{class}`trx::TrxFile` is templated on the positions dtype (`Eigen::half`,
+`float`, or `double`). Positions and DPV arrays are exposed as
+`Eigen::Matrix<DT, ...>` directly — no element-wise conversion. Use this
+when the dtype is known, or when you are performing per-vertex arithmetic and
+want the compiler to enforce type consistency.
+
+```cpp
+auto reader = trx::load<float>("tracks.trx");
+auto& trx   = *reader;
+
+// trx.streamlines->_data is Eigen::Matrix<float, Dynamic, 3>
+std::cout << trx.streamlines->_data.rows() << " vertices\n";
+
+reader->close();
+```
+
+The recommended typed entry point is {func}`trx::with_trx_reader`, which
+detects the dtype at runtime and dispatches to the correct instantiation:
+
+```cpp
+trx::with_trx_reader("tracks.trx", [](auto& trx) {
+  // trx is TrxFile<DT> for the detected dtype
+  std::cout << trx.num_vertices() << "\n";
+});
+```
+
+## TrxReader\<DT> — RAII lifetime management
+
+{class}`trx::TrxReader` is a thin RAII wrapper around {class}`trx::TrxFile`.
+When a TRX zip is loaded, trx-cpp extracts it to a temporary directory.
+`TrxReader` owns that directory and removes it when it goes out of scope,
+ensuring no temporary files are leaked.
+
+In most cases you do not need to instantiate `TrxReader` directly. The
+convenience functions `trx::load_any` and `trx::with_trx_reader` handle
+the lifetime automatically. `TrxReader` is available for advanced use cases
+where explicit control over the backing resource lifetime is required — for
+example, when passing a `TrxFile` across a function boundary and needing the
+temporary directory to outlive the calling scope.
+
+## Summary
+
+| Class           | Dtype                       | Best for                  |
+| --------------- | --------------------------- | ------------------------- |
+| `AnyTrxFile`    | Runtime (read from file)    | Inspection, generic tools |
+| `TrxFile<DT>`   | Compile-time                | Per-vertex computation    |
+| `TrxReader<DT>` | Compile-time + RAII cleanup | Explicit lifetime control |