Migrate documentation from sphinx_tabs to sphinx-design

[Copilot]

Change Description

• My PR includes a link to the issue that I am addressing

Documentation builds were failing on Sphinx 8.0+ due to sphinx_tabs attempting to access a deprecated 'backrefs' attribute, resulting in KeyError.

Solution Description

Migrated from unmaintained sphinx_tabs to actively maintained sphinx-design extension.

Dependencies

• docs/requirements.txt: Removed sphinx-tabs dependency
• docs/conf.py: Removed sphinx_tabs.tabs from extensions list

Syntax Migration (12 instances across 6 files)

• architecture_overview.rst (1)
• configuration.rst (2)
• data_set_splits.rst (3)
• external_libraries.rst (1)
• model_comparison.rst (1)
• verbs.rst (4)

Tab directive syntax updated:

-.. tabs::
-    .. group-tab:: Notebook
-        <content>
-    .. group-tab:: CLI
-        <content>

+.. tab-set::
+    .. tab-item:: Notebook
+        <content>
+    .. tab-item:: CLI
+        <content>

sphinx-design is fully compatible with Sphinx 8.0+ and provides equivalent tabbed content functionality.

Original prompt

Problem

The documentation build is failing due to a compatibility issue between sphinx_tabs and newer versions of Sphinx (8.0+). The error occurs in sphinx_tabs/tabs.py when trying to access a 'backrefs' attribute that no longer exists:

KeyError: 'backrefs'

Failing job: https://github.com/lincc-frameworks/hyrax/actions/runs/21183334872/job/60931096491

Solution

Migrate from the outdated sphinx_tabs extension to the modern sphinx-design extension, which is actively maintained and compatible with current Sphinx versions.

Required Changes

1. Update docs/requirements.txt

Replace sphinx_tabs with sphinx-design.

2. Update docs/conf.py

In the extensions list, replace 'sphinx_tabs.tabs' with 'sphinx_design'.

3. Update docs/architecture_overview.rst

Convert the tab syntax from sphinx_tabs to sphinx-design:

Current (lines 17-32):

.. tabs::

    .. group-tab:: Notebook

        .. code-block:: python

           from hyrax import Hyrax

           h = Hyrax(config_file = 'my_config.toml')
           h.train()

    .. group-tab:: CLI

        .. code-block:: bash

           >> hyrax train -c my_config.toml

New:

.. tab-set::

    .. tab-item:: Notebook

        .. code-block:: python

           from hyrax import Hyrax

           h = Hyrax(config_file = 'my_config.toml')
           h.train()

    .. tab-item:: CLI

        .. code-block:: bash

           >> hyrax train -c my_config.toml

Summary of Changes

• .. tabs:: → .. tab-set::
• .. group-tab:: → .. tab-item::
• All content and indentation remains the same

This will resolve the build failure and modernize the documentation tooling.

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This pull request migrates Hyrax documentation from the unmaintained sphinx_tabs extension to the actively maintained sphinx-design extension to resolve build failures on Sphinx 8.0+. The migration addresses a KeyError: 'backrefs' issue caused by sphinx_tabs attempting to access deprecated Sphinx attributes.

Changes:

• Removed sphinx-tabs dependency and sphinx_tabs.tabs extension reference
• Updated tab directive syntax from .. tabs:: / .. group-tab:: to .. tab-set:: / .. tab-item:: across all documentation files
• Migrated 12 instances of tab directives across 6 RST files with consistent syntax conversion

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/requirements.txt	Removed deprecated sphinx-tabs dependency (sphinx-design already present)
docs/conf.py	Removed sphinx_tabs.tabs from extensions list
docs/architecture_overview.rst	Migrated 1 tab directive to sphinx-design syntax
docs/configuration.rst	Migrated 2 tab directives to sphinx-design syntax
docs/data_set_splits.rst	Migrated 3 tab directives to sphinx-design syntax
docs/external_libraries.rst	Migrated 1 tab directive to sphinx-design syntax
docs/model_comparison.rst	Migrated 1 tab directive to sphinx-design syntax
docs/verbs.rst	Migrated 4 tab directives to sphinx-design syntax

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.31%. Comparing base (1ebe5d5) to head (3641f06).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #600   +/-   ##
=======================================
  Coverage   62.31%   62.31%           
=======================================
  Files          53       53           
  Lines        5235     5235           
=======================================
  Hits         3262     3262           
  Misses       1973     1973           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gitosaurus]

LGTM. Local build seems to render properly.

[drewoldag]

Looks good to me!