docs: large documentation update. Add examples, add specs, add scripts

.github/workflows/docbuild.yml

@@ -35,7 +35,7 @@ jobs:
     - name: Build docs
       run: |
         cd docs
-        make html
+        SPHINXOPTS="-W" make html
     - name: Upload docs
       uses: actions/upload-artifact@v4
       with:

.gitignore

@@ -134,7 +134,10 @@ dmypy.json
 .vscode/
 
 tmp/
+auto_examples/
 CLAUDE.md
 claude.md
 agents.md
 AGENTS.md
+sg_execution_times.rst
+

.spin/cmds.py

@@ -204,10 +204,19 @@ def docs(clean, open_browser):
         click.echo("Cleaning build directory...")
         build_dir = os.path.join(docs_dir, "_build")
         if os.path.exists(build_dir):
-            import shutil
-
             shutil.rmtree(build_dir)
 
+        # Clean sphinx-gallery generated files
+        gallery_dir = os.path.join(docs_dir, "source", "auto_examples")
+        if os.path.exists(gallery_dir):
+            click.echo("Cleaning sphinx-gallery generated files...")
+            shutil.rmtree(gallery_dir)
+
+        # Clean sphinx-gallery execution times file
+        sg_times = os.path.join(docs_dir, "source", "sg_execution_times.rst")
+        if os.path.exists(sg_times):
+            os.remove(sg_times)
+
     click.echo("Building documentation...")
     cmd = ["make", "-C", docs_dir, "html"]
     result = run(cmd, capture=False, check=False)

docs/source/conf.py

@@ -60,8 +60,19 @@
     'sphinx.ext.autosummary',
     'autoapi.extension',
     'numpydoc',
+    'sphinx_gallery.gen_gallery',
+    'sphinx_design',
 ]
 
+# Suppress known deprecation warnings from dependencies
+# astroid 4.x deprecation - will be fixed when sphinx-autoapi updates for astroid 5.x
+import warnings
+warnings.filterwarnings(
+    'ignore',
+    message="importing .* from 'astroid' is deprecated",
+    category=DeprecationWarning
+)
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -84,6 +95,10 @@
 html_static_path = ['../_static']
 html_logo = "../_static/trx_logo.png"
 
+html_sidebars = {
+    "scripts": [],
+    "trx_specifications": [],
+}
 
 html_theme_options = {
     "icon_links": [
@@ -106,9 +121,24 @@
     },
     "navbar_start": ["navbar-logo", "version-switcher"],
     "show_version_warning_banner": True,
+    # Show table of contents on each page (section navigation)
+    "secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink"],
+    "show_toc_level": 2,
 }
 
 
 autoapi_type = 'python'
 autoapi_dirs = ['../../trx']
 autoapi_ignore = ['*test*', '*version*']
+
+# Sphinx gallery configuration
+sphinx_gallery_conf = {
+     'examples_dirs': '../../examples',
+     'gallery_dirs': 'auto_examples',
+     'within_subsection_order': 'NumberOfCodeLinesSortKey',
+     'reference_url': {
+         'numpy': 'https://numpy.org/doc/stable/',
+         'nibabel': 'https://nipy.org/nibabel/',
+     },
+     'default_thumb_file': os.path.join(os.path.dirname(__file__), '..', '_static', 'trx_logo.png'),
+}

docs/source/dev.rst

@@ -3,6 +3,11 @@ Developer Guide
 
 This guide provides detailed information for developers working on TRX-Python.
 
+.. toctree::
+   :maxdepth: 1
+
+   contributing
+
 Installation for Development
 ----------------------------
 

docs/source/index.rst

@@ -11,8 +11,34 @@ exchange, interoperability, and state-of-the-art analyses, acting as a
 community-driven replacement for the myriad existing file formats.
 
 
-Why TRX?
+Getting Started
 ~~~~~~~~~~~~~~~
+
+New to TRX? Start here:
+
+1. **Understand the format**: Read the :doc:`trx_specifications` to understand the TRX file structure
+2. **Learn by example**: Follow our :doc:`auto_examples/index` to learn how to read, write, and manipulate TRX files
+3. **Use the CLI tools**: Check out the :doc:`scripts` documentation for command-line operations
+
+.. grid:: 2
+
+   .. grid-item-card:: Tutorials
+      :link: auto_examples/index
+      :link-type: doc
+
+      Learn how to work with TRX files through hands-on tutorials covering
+      reading/writing files, working with groups, and using metadata.
+
+   .. grid-item-card:: TRX Specifications
+      :link: trx_specifications
+      :link-type: doc
+
+      Complete technical specifications of the TRX file format including
+      header fields, array structures, and naming conventions.
+
+
+Why TRX?
+~~~~~~~~
 File formats that store the results of computational tractography were typically
 developed within specific software packages. This approach has facilitated a
 myriad of applications, but this development approach has also generated
@@ -44,13 +70,19 @@ Development of TRX is supported by `NIMH grant 1R01MH126699 <https://reporter.ni
    :maxdepth: 2
    :caption: User Guide:
 
+   trx_specifications
    scripts
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials:
+
+   auto_examples/index
+
 .. toctree::
    :maxdepth: 2
    :caption: Development:
 
-   contributing
    dev
 
 .. toctree::

docs/source/scripts.rst

@@ -1,3 +1,5 @@
+:html_theme.sidebar_secondary.remove:
+
 Command-line Interface
 ======================