DOCS: Overhaul front page, remove redundancies.

README.md

@@ -3,7 +3,7 @@
 [![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.
+A C++17 library for reading, writing, and memory-mapping the [TRX tractography format](tee-ar-ex.github.io) — efficient storage for large-scale tractography data.
 
 ## Features
 

docs/_templates/implementation-links.html

@@ -1,7 +1,7 @@
 <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-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>

docs/building.md

@@ -128,9 +128,16 @@ Tests require GTest to be discoverable by CMake (e.g., via a system package or
 `GTest_DIR`). If GTest is not found, tests will be skipped.
 zlib must be discoverable by CMake (`ZLIB::ZLIB`), including for NIfTI I/O.
 
-## Building documentation:
+## Building documentation
 
-Building the docs requires both Doxygen and `sphinx-build` on your PATH.
+Building the docs requires both Doxygen and `sphinx-build` on your PATH, as
+well as some other python dependencies. To install those, run:
+
+```bash
+python -m pip install -r docs/requirements.txt
+```
+
+Then, to build the docs, run:
 
 ```bash
 cmake -S . -B build \

docs/conf.py

@@ -8,6 +8,7 @@
     "breathe",
     "exhale",
     "sphinx.ext.autosectionlabel",
+    "sphinx_design",
 ]
 
 root_doc = "index"
@@ -49,8 +50,10 @@
 }
 
 myst_enable_extensions = [
-    "colon_fence",
+ "colon_fence",
     "deflist",
+    "fieldlist",
+    "html_image",
     "tasklist",
 ]
 

docs/index.md

@@ -10,62 +10,60 @@
 :target: https://codecov.io/gh/tee-ar-ex/trx-cpp
 ```
 
-A C++17 library for reading, writing, and memory-mapping the TRX tractography
-format.
+A C++17 library for reading, writing, and memory-mapping the [TRX tractography
+format](https://tee-ar-ex.github.io).
 
+::::{grid} 2
+:::{grid-item-card} Getting Started
 ```{toctree}
-:caption: Getting Started
-:maxdepth: 2
-
+:maxdepth: 1
 introduction
 quick_start
 building
 ```
+:::
 
+:::{grid-item-card} User Guide
 ```{toctree}
-:caption: User Guide
-:maxdepth: 2
-
-concepts
+:maxdepth: 1
 api_layers
 reading
 writing
 streaming
 spatial_queries
 nifti
 ```
+:::
+::::
 
+::::{grid} 2
+:::{grid-item-card} Integration Guide
 ```{toctree}
-:caption: Integration Guide
 :maxdepth: 2
-
 integration
 ```
+:::
 
+:::{grid-item-card} Performance
 ```{toctree}
-:caption: Performance
 :maxdepth: 2
-
 benchmarks
 ```
+:::
+::::
 
+::::{grid}
+:::{grid-item-card} Contributing
 ```{toctree}
-:caption: TRX Format
 :maxdepth: 2
-
-spec
-```
-
-```{toctree}
-:caption: Contributing
-:maxdepth: 2
-
 linting
 ```
+:::
 
+:::{grid-item-card} API Reference
 ```{toctree}
-:caption: API Reference
 :maxdepth: 2
-
 api/library_root
 ```
+:::
+::::

docs/requirements.txt

@@ -3,3 +3,4 @@ breathe
 exhale
 pydata-sphinx-theme
 myst-parser
+sphinx-design