DOC: Removes fencepost section, because this is part of the spec now.

.github/workflows/docs.yml

@@ -20,7 +20,7 @@ jobs:
           python-version: '3.11'
       - name: Install Python dependencies
         run: |
-          pip install sphinx myst-parser pydata-sphinx-theme sphinx-js
+          pip install sphinx myst-parser pydata-sphinx-theme sphinx-js sphinx-design
       - name: Install JSDoc
         run: npm install -g jsdoc
       - name: Build docs

Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = docs
+BUILDDIR      = docs/_build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -14,6 +14,21 @@ node bench.mjs dpsv.trx
 
 ## Documentation
 
-Full documentation is available at (GitHub Pages URL).
+Full documentation is available at the
+[project website](https://tee-ar-ex.github.io/trx-javascript).
+
+### Building the documentation
+
+To build the documentationl locally, install jsdoc:
+
+   npm install -g jsdoc
+
+And python dependencies:
+
+   pip install sphinx myst-parser pydata-sphinx-theme sphinx-js
+
+And then run `make html`
+
+
 
 

docs/conf.py

@@ -12,6 +12,7 @@
     'myst_parser',
     'sphinx_js',
     'sphinx.ext.autosectionlabel',
+    'sphinx_design',
 ]
 
 js_source_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
@@ -52,6 +53,8 @@
 myst_enable_extensions = [
     "colon_fence",
     "deflist",
+    "fieldlist",
+    "html_image",
     "tasklist",
 ]
 

docs/implementation-notes.md

@@ -6,17 +6,6 @@ The TRX specification allows streamline positions to use the float16 datatype,
 which is not native to JavaScript. This code converts float16 values to float32
 using a lookup table for performance.
 
-## Fencepost Problem
-
-The TRX specification stores NB_STREAMLINES values in the offsets array, with
-each value pointing to the start of that streamline. One must use the length of
-the positions array or the header to infer the end of the final streamline.
-
-This code returns an offset array with NB_STREAMLINES + 1 values to solve the
-[fencepost problem](https://icarus.cs.weber.edu/~dab/cs1410/textbook/3.Control/fencepost.html)
-for the final streamline. This simplifies and accelerates display code, but you
-must be aware of this modification when comparing with other implementations.
-
 ## Endianness
 
 The TRX specification requires little-endian byte order. The current code only

docs/index.md

@@ -1,15 +1,24 @@
-# trx-javascript
+# TRX in javascript
 
-A minimal JavaScript reader for brain tractography streamline formats:
-**TRX**, **TRK**, **TCK**, **VTK**, and **TT** (DSI Studio).
+This library provides a minimal JavaScript reader for brain tractography streamline
+formats, including **TRX**, but also **TRK**, **TCK**, **VTK**, and
+**TT** ([DSI Studio](https://dsi-studio.labsolver.org/)).
 
-```{toctree}
-:maxdepth: 2
-:caption: Contents
 
+::::{grid} 2
+:::{grid-item-card}  Usage documentation
+```{toctree}
+:maxdepth: 1
 getting-started
 api
 formats
+```
+:::
+:::{grid-item-card}  Development and benchmarks
+```{toctree}
+:maxdepth: 2
 implementation-notes
 benchmark
 ```
+:::
+::::