Unify and elaborate documentation

.github/workflows/deploy.yml

@@ -1,14 +1,18 @@
 name: Deploy website
 
-on: [push, pull_request]
+on:
+  push:
+    branches: [main]
+  pull_request:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 permissions:
-  contents: write
-
+  contents: read
+  pages: write
+  id-token: write
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -31,11 +35,19 @@ jobs:
       run: |
         make html
     - name: Upload site
-      uses: actions/upload-artifact@v4
-      with:
-        name: site
-        path: build/html
-    - name: Publish docs to Github Pages
-      uses: JamesIves/github-pages-deploy-action@releases/v4
+      uses: actions/upload-pages-artifact@v4
       with:
-        folder: build/html
+        path: _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

.gitignore

@@ -1,2 +1,2 @@
 .DS_Store
-build/*
+_build/*

Makefile

@@ -6,7 +6,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

README.md

@@ -1,3 +1,56 @@
 # tee-ar-ex.github.io
 
-A website for the TRX file format.
+A website for the TRX file format, built with Sphinx and the MyST parser.
+
+## Building the documentation
+
+### Prerequisites
+
+- Python 3.9+
+
+### Local build
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/tee-ar-ex/tee-ar-ex.github.io.git
+   cd tee-ar-ex.github.io
+   ```
+
+2. Create and activate a virtual environment (optional but recommended):
+
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # Windows: venv\Scripts\activate
+   ```
+
+3. Install dependencies:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. Build the documentation:
+
+   ```bash
+   make html
+   ```
+
+5. Open `_build/html/index.html` in your browser.
+
+### Development workflow
+
+To rebuild automatically while editing:
+
+```bash
+sphinx-autobuild source _build/html
+```
+
+Note: `sphinx-autobuild` needs to be installed separately
+(`pip install sphinx-autobuild`).
+
+### Deployment
+
+The site is automatically deployed to GitHub Pages via GitHub Actions on
+pushes to `main`. Pull requests trigger a build to validate changes without
+deploying.

requirements.txt

@@ -1,3 +1,5 @@
 sphinx
 myst-parser
-pydata_sphinx_theme
+pydata_sphinx_theme
+sphinxcontrib-bibtex
+sphinx-design

source/_templates/implementation-links.html

@@ -0,0 +1,11 @@
+<div class="sidebar-implementation-links">
+  <h3>TRX specification and implementations</h3>
+  <ul>
+    <li><a href="https://github.com/tee-ar-ex/trx-spec">TRX Specification</a></li>
+    <li><a href="https://tee-ar-ex.github.io/trx-python">Python</a></li>
+    <li><a href="https://tee-ar-ex.github.io/trx-cpp">C++</a></li>
+    <li><a href="https://tee-ar-ex.github.io/trx-rs">Rust</a></li>
+    <li><a href="https://tee-ar-ex.github.io/trx-javascript">JavaScript</a></li>
+    <li><a href="https://tee-ar-ex.github.io/trx-pascal">Pascal</a></li>
+  </ul>
+</div>

source/bib.md

@@ -0,0 +1,9 @@
+# Bibliography
+
+
+```{eval-rst}
+
+.. bibliography::
+   :all:
+
+```

source/concepts.md

@@ -0,0 +1,98 @@
+# Core Concepts
+
+This page explains how the TRX format represents tractography data on disk and
+in memory.
+
+## The TRX format
+
+A TRX file is a ZIP archive (or on-disk directory) whose layout directly
+encodes its data model:
+
+- `header.json` — spatial metadata
+- `positions.<dim>.<dtype>` — all streamline vertices in a single flat array
+- `offsets.<dtype>` — prefix-sum index from streamlines into positions
+- `dpv/<name>.<dtype>` — per-vertex metadata arrays
+- `dps/<name>.<dtype>` — per-streamline metadata arrays
+- `groups/<name>.uint32` — named index sets of streamlines
+- `dpg/<group>/<name>.<dtype>` — per-group metadata arrays
+
+Coordinates are stored in **RAS+ world space** (millimeters), matching the
+convention used by MRtrix3 `.tck` and NIfTI qform outputs.
+
+## Positions array
+
+All streamline vertices are stored in a single flat matrix of shape
+`(NB_VERTICES, 3)`. Keeping all vertices contiguous enables efficient memory
+mapping and avoids per-streamline allocations.
+
+## Offsets and the sentinel
+
+`offsets` is a prefix-sum index of length `NB_STREAMLINES + 1`. Element *i* is
+the offset in `positions` of the first vertex of streamline *i*. The final
+element is a **sentinel** equal to `NB_VERTICES`, which makes length
+computation trivial without special-casing the last streamline:
+
+```
+length_i = offsets[i + 1] - offsets[i]
+```
+
+This design avoids per-streamline allocations and makes slicing the global
+positions array fast and uniform.
+
+## Data per vertex (DPV)
+
+A DPV array stores one value per vertex in `positions`. It has shape
+`(NB_VERTICES, 1)` for scalar fields or `(NB_VERTICES, N)` for vector-valued
+fields. Typical uses:
+
+- FA values along the tract
+- Per-point RGB colors
+- Confidence or weight measures per vertex
+
+DPV arrays live under `dpv/` and are memory-mapped in the same way as
+`positions`.
+
+## Data per streamline (DPS)
+
+A DPS array stores one value per streamline. It has shape
+`(NB_STREAMLINES, 1)` or `(NB_STREAMLINES, N)`. Typical uses:
+
+- Mean FA or average curvature per tract
+- Per-streamline cluster labels
+- Tractography algorithm weights
+
+DPS arrays live under `dps/` and are loaded as typed matrix fields. If the
+on-disk dtype differs from the requested typed reader dtype, values are
+converted during load.
+
+## Groups
+
+A group is a named list of streamline indices stored as a `uint32` array under
+`groups/`. Groups enable sparse, overlapping labeling: a streamline can belong
+to multiple groups, and groups can have different sizes. Typical uses:
+
+- Bundle labels (`CST_L`, `CC`, `SLF_R`, ...)
+- Cluster assignments from QuickBundles or similar algorithms
+- Connectivity subsets (streamlines connecting two ROIs)
+
+## Data per group (DPG)
+
+DPG attaches metadata to a group. Each group folder `dpg/<name>/` can contain
+any number of scalar or vector arrays. Typical uses:
+
+- Mean FA across the bundle
+- Per-bundle display color
+- Volume or surface-area estimates
+
+## Header
+
+`header.json` stores:
+
+- `VOXEL_TO_RASMM` — 4x4 affine mapping voxel indices to RAS+ world
+  coordinates (mm)
+- `DIMENSIONS` — reference image grid dimensions as three `uint16` values
+- `NB_STREAMLINES` — number of streamlines (`uint32`)
+- `NB_VERTICES` — total number of vertices across all streamlines (`uint64`)
+
+The header is primarily for human readability and downstream compatibility. The
+authoritative sizes come from the array dimensions themselves.

source/conf.py

@@ -6,17 +6,35 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'tee-ar-ex'
-copyright = '2026, TRX developers'
-author = 'TRX developers'
+from datetime import datetime as dt
+
+project = 'TRX'
+copyright = f'2021-{dt.now().year}, The TRX developers'
+author = 'The TRX developers'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     "myst_parser",
+    "sphinxcontrib.bibtex",
+    "sphinx_design",
     ]
 
+bibtex_bibfiles = ['references.bib']
+bibtex_default_style = 'plain'
+bibtex_reference_style = 'author_year'
+
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "fieldlist",
+    "html_image",
+    "tasklist",
+]
+myst_heading_anchors = 3
+
 templates_path = ['_templates']
 exclude_patterns = ['.DS_Store']
 source_suffix = ['.rst', '.md']
@@ -32,9 +50,15 @@
 html_logo = "_static/logo.png"
 
 html_theme_options = {
-    "secondary_sidebar_items": [],
+    "secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink"],
     "use_edit_page_button": True,
     "icon_links": [
+        {
+            "name": "Home",
+            "url": "index.html",
+            "icon": "fa-solid fa-home",
+            "attributes": {"target": "_self"},
+        },
         {
             "name": "GitHub",
             "url": "https://github.com/tee-ar-ex/",
@@ -49,4 +73,8 @@
     "github_repo": "tee-ar-ex.github.io",
     "github_version": "main",
     "doc_path": "source",
+}
+
+html_sidebars = {
+    "**": ["sidebar-nav-bs.html", "implementation-links.html"],
 }