Unify and elaborate documentation

[arokem]

This site will eventually be the one entry point into the ecosystem and will aggregate language-agnostic descriptions of the specification, and explanations, a bit of history of the format and a roadmap for the future.

[Copilot]

Pull request overview

This PR restructures the Sphinx documentation site to serve as a single entry point for the TRX ecosystem, adding new content pages (concepts/spec/design/history/software), bibliography support, and updated GitHub Pages deployment.

Changes:

• Added several new documentation pages covering TRX concepts, specification, design rationale, software integrations, and project history.
• Added bibliography/citation support (BibTeX + MyST) and wired citations into the docs.
• Updated build/deploy plumbing (Sphinx build dir, gitignore, and GitHub Pages workflow) and added a custom sidebar links template.

Reviewed changes

Copilot reviewed 13 out of 15 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
source/specification.md	Adds an initial TRX format specification page and example structure/code.
source/software.md	Adds a catalog of software that integrates TRX, with citations.
source/references.bib	Adds BibTeX references used by the documentation citations.
source/index.md	Replaces the old landing page with a MyST+Sphinx toctree-based index and citations.
source/history.md	Adds historical background and adoption notes, with citations/links.
source/design.md	Adds design rationale and trade-off explanations for TRX.
source/conf.py	Enables bibtex + additional MyST features and changes theme/sidebar configuration.
source/concepts.md	Adds an overview of TRX’s on-disk model and core concepts.
source/capsule.md	Removes the CodeOcean widget embed.
source/bib.md	Adds a generated bibliography page.
source/_templates/implementation-links.html	Adds a custom sidebar template linking to implementations/spec repo.
requirements.txt	Adds sphinxcontrib-bibtex dependency for citations.
Makefile	Changes Sphinx build output directory to _build.
.gitignore	Updates ignored build output path to _build/*.
.github/workflows/deploy.yml	Switches to GitHub Pages artifact + deploy-pages workflow structure.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[arokem]

Hmm. Looks like maybe this is something that was added in the C++ implementation? It's not in the original spec.

[frheault]

I remember @neurolabusc asking us to add this to the spec and I believe we did. trx-python follow this (as well as Rust and C++).

[arokem]

I don't see it, so I will post an issue on the spec repo to implement this.

[frheault]

That's amazing !

I have general comments about the presentation (but the content seems great !)

1. Even if it is trival, maybe add build instructions to the README

2. source/index.md should have a collapsible table of contents (should I do that in a later PR?).

3. The links on the left has a title ''TRX specification and implementations'', but it is not clear these are external links. It should be ''external links to implementations documentation and repositories'' or something like that

4. At the top ''Core Concepts TRX Specification Design Rationale Software The history of the TRX file format Bibliography''
   I would rename ''The history of the TRX file format'' to History of TRX or Timeline of TRX and I believe have an extra link to the landing page there would be useful (the only way to come back to the first page is clicking on the TRX logo?)

5. The external link for CPP is 404, should be https://trx-cpp.readthedocs.io/en/latest/introduction.html (I think)

6. Should we plan for a centralized contributions page (in History) ? Anyone that brainstormed about specs, code a chunk of one of the languages, integration into software (more than an import), etc.

7. The subsection on Compression, I believe it is useful (and important) to say the specification is compatible with linearization compression (fairly simple, but we are still just lines in 3D). Also optional, lossy because it removes points. This leave the user with the possibility to linearize, save to float16 and compress the ZIP for large dataset and cold storage (I like that we have multiple way to attack size)
   https://www.frontiersin.org/journals/neuroinformatics/articles/10.3389/fninf.2017.00042/full

[frheault]

Also for the Software section, I would add to the top as a disclaimer that not all software have the same functionallities and integration. We can assure that it load and save, but it is possible that information related to the data_per_* are not used or that complex operation (lazy loading or saving, advanced slicing, etc.) are not implemented in some language.

Also I would add the following (to show proof of life):
tractometry/pyAFQ#208
dipy/dipy#3587
SlicerDMRI/SlicerDMRI#250
https://git.fmrib.ox.ac.uk/fsl/fsleyes/fsleyes/-/merge_requests/504
daducci/COMMIT#163
niivue/niivue#841
InsightSoftwareConsortium/ITK#6687
MRtrix3/mrtrix3#3415

(Cant find any reference to TRX in Trekker, can't tell I know where it is in QSIPrep & QSIRecon (is it a default, do they export BIDS-Like and picked TRX as output?, I think these should be clarifiied)

[arokem]

Even if it is trival, maybe add build instructions to the README

Added in 987c936

source/index.md should have a collapsible table of contents (should I do that in a later PR?).

Added in 3de2569

The links on the left has a title ''TRX specification and implementations'', but it is not clear these are external links. It should be ''external links to implementations documentation and repositories'' or something like that

Arguably, these are not external links. They are all within the tee-ar-ex.github.io namespace. This is also responsive to reviews that we received that requested something that is more unified across all the implementations. This way, they are all part of one big site. I have also made it so that regardless of which implementation you are reading, when you click on the logo in the top left you land in the main tee-ar-ex.github.io website.

At the top ''Core Concepts TRX Specification Design Rationale Software The history of the TRX file format Bibliography''
I would rename ''The history of the TRX file format'' to History of TRX or Timeline of TRX

Done in b98001c

and I believe have an extra link to the landing page there would be useful (the only way to come back to the first page is clicking on the TRX logo?)

Added in 23abf40

The external link for CPP is 404, should be https://trx-cpp.readthedocs.io/en/latest/introduction.html (I think)

This should be fixed when tee-ar-ex/trx-cpp#51 is merged.

Should we plan for a centralized contributions page (in History) ? Anyone that brainstormed about specs, code a chunk of one of the languages, integration into software (more than an import), etc.

Let's do that separately.

The subsection on Compression, I believe it is useful (and important) to say the specification is compatible with linearization compression (fairly simple, but we are still just lines in 3D). Also optional, lossy because it removes points. This leave the user with the possibility to linearize, save to float16 and compress the ZIP for large dataset and cold storage (I like that we have multiple way to attack size)
https://www.frontiersin.org/journals/neuroinformatics/articles/10.3389/fninf.2017.00042/full

Added in d0d0e07

[arokem]

Added links to PRs in dcd7d9b

[arokem]

I think this is ready to go @frheault! But let me know if you see anything that needs fixing.