🛠️ Refactor Sphinx-Needs DataTables integration to use GridJS

docs/_static/_css/shared.css

@@ -123,7 +123,7 @@ svg.sn-flow-chart {
 }
 
 table.needs-grid-example {
-    border: 1px solid var(--color-table-border);
+    border: 1px solid var(--sn-color-table-border);
 }
 
 :root {

docs/_static/_css/sphinx_rtd_theme.css

@@ -10,9 +10,3 @@ div.wy-table-responsive {
     overflow-x: auto !important;
 }
 
-/* a lot of components, like paragraphs and header, do not have a top margin
-so the datatable does not have a gap to the subsequent element
-*/
-div.dataTables_wrapper {
-    margin-bottom: 2em;
-}

requirements-dev.lock

@@ -0,0 +1,86 @@
+# generated by rye
+# use `rye lock` or `rye sync` to update this lockfile
+#
+# last locked with the following flags:
+#   pre: false
+#   features: []
+#   all-features: false
+#   with-sources: false
+#   generate-hashes: false
+#   universal: false
+
+-e file:.
+alabaster==0.7.16
+    # via sphinx
+attrs==25.3.0
+    # via jsonschema
+    # via referencing
+babel==2.17.0
+    # via sphinx
+certifi==2025.4.26
+    # via requests
+charset-normalizer==3.4.2
+    # via requests
+docutils==0.21.2
+    # via sphinx
+idna==3.10
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==8.7.0
+    # via sphinx
+jinja2==3.1.6
+    # via sphinx
+jsonschema==4.24.0
+    # via sphinx-needs
+jsonschema-specifications==2025.4.1
+    # via jsonschema
+markupsafe==3.0.2
+    # via jinja2
+packaging==25.0
+    # via sphinx
+pygments==2.19.1
+    # via sphinx
+referencing==0.36.2
+    # via jsonschema
+    # via jsonschema-specifications
+requests==2.32.4
+    # via requests-file
+    # via sphinx
+    # via sphinx-needs
+requests-file==2.1.0
+    # via sphinx-needs
+rpds-py==0.25.1
+    # via jsonschema
+    # via referencing
+snowballstemmer==3.0.1
+    # via sphinx
+sphinx==7.4.7
+    # via sphinx-data-viewer
+    # via sphinx-needs
+    # via sphinxcontrib-jquery
+sphinx-data-viewer==0.1.5
+    # via sphinx-needs
+sphinxcontrib-applehelp==2.0.0
+    # via sphinx
+sphinxcontrib-devhelp==2.0.0
+    # via sphinx
+sphinxcontrib-htmlhelp==2.1.0
+    # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-needs
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==2.0.0
+    # via sphinx
+sphinxcontrib-serializinghtml==2.0.0
+    # via sphinx
+tomli==2.2.1
+    # via sphinx
+    # via sphinx-needs
+typing-extensions==4.14.0
+    # via referencing
+urllib3==2.4.0
+    # via requests
+zipp==3.23.0
+    # via importlib-metadata

requirements.lock

@@ -0,0 +1,86 @@
+# generated by rye
+# use `rye lock` or `rye sync` to update this lockfile
+#
+# last locked with the following flags:
+#   pre: false
+#   features: []
+#   all-features: false
+#   with-sources: false
+#   generate-hashes: false
+#   universal: false
+
+-e file:.
+alabaster==0.7.16
+    # via sphinx
+attrs==25.3.0
+    # via jsonschema
+    # via referencing
+babel==2.17.0
+    # via sphinx
+certifi==2025.4.26
+    # via requests
+charset-normalizer==3.4.2
+    # via requests
+docutils==0.21.2
+    # via sphinx
+idna==3.10
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==8.7.0
+    # via sphinx
+jinja2==3.1.6
+    # via sphinx
+jsonschema==4.24.0
+    # via sphinx-needs
+jsonschema-specifications==2025.4.1
+    # via jsonschema
+markupsafe==3.0.2
+    # via jinja2
+packaging==25.0
+    # via sphinx
+pygments==2.19.1
+    # via sphinx
+referencing==0.36.2
+    # via jsonschema
+    # via jsonschema-specifications
+requests==2.32.4
+    # via requests-file
+    # via sphinx
+    # via sphinx-needs
+requests-file==2.1.0
+    # via sphinx-needs
+rpds-py==0.25.1
+    # via jsonschema
+    # via referencing
+snowballstemmer==3.0.1
+    # via sphinx
+sphinx==7.4.7
+    # via sphinx-data-viewer
+    # via sphinx-needs
+    # via sphinxcontrib-jquery
+sphinx-data-viewer==0.1.5
+    # via sphinx-needs
+sphinxcontrib-applehelp==2.0.0
+    # via sphinx
+sphinxcontrib-devhelp==2.0.0
+    # via sphinx
+sphinxcontrib-htmlhelp==2.1.0
+    # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-needs
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==2.0.0
+    # via sphinx
+sphinxcontrib-serializinghtml==2.0.0
+    # via sphinx
+tomli==2.2.1
+    # via sphinx
+    # via sphinx-needs
+typing-extensions==4.14.0
+    # via referencing
+urllib3==2.4.0
+    # via requests
+zipp==3.23.0
+    # via importlib-metadata

sphinx_needs/css/common/needstable.css

@@ -21,86 +21,123 @@ div.needstable_wrapper {
     padding: 0;
 }
 
-/* These are "overrides" for CSS added by the bundled https://datatables.net JS package */
+table.docutils.docutils td, table.docutils.docutils th {
+    background: var(--sn-color-datatable-body-bg);
+    border: 1px solid var(--sn-color-table-border);
+    color: var(--sn-color-datatable-label);
+}
 
-table.dataTable {
-    border-collapse: collapse;
-    border: none;
+table.docutils.docutils th {
+    border-bottom: 1px solid var(--sn-color-datatable-btn-border);
 }
+/* GridJS styles for to override the default GridJS styles
+to match the Sphinx Needs theme and to ensure a consistent look and feel
+with the rest of the Sphinx Needs documentation.
 
-table.dataTable tbody tr {
-    background-color: var(--sn-color-datatable-body-bg);
+The 3 sections of a GridJS container .gridjs-head, .gridjs-wrapper and .gridjs-footer */
+div.gridjs-container {
+    color: var(--sn-color-datatable-label);
 }
 
-div.dataTables_length {
-    margin-bottom: 10px;
+div.gridjs-wrapper {
+    border-radius: 0px;
+    box-shadow: none;
 }
 
-div.dataTables_wrapper {
-    overflow-x: auto;
-    padding: 0px 5px;
-    /*Space needed for table borders */
+div.gridjs-footer {
+    background-color: var(--sn-color-datatable-body-bg);
+    border: 1px solid var(--sn-color-datatable-btn-border);
+    box-shadow: none;
+    padding: 12px;
+    border-top-width: 0px;
 }
 
-.dataTables_wrapper .dataTables_paginate .paginate_button {
-    padding: 0.15em 0.75em;
-    background: none;
+/* .gridjs-head */
+.gridjs-search {
+    float: left;
 }
 
-.dataTables_wrapper .dataTables_paginate .paginate_button.current,
-.dataTables_wrapper .dataTables_paginate .paginate_button.current:hover {
-    background: none;
+div.gridjs-download-btns {
+    float: right;
 }
 
-div.dataTables_length select {
-    background: none;
-    color: var(--sn-color-datatable-label);
-    border: 1px solid var(--sn-color-datatable-btn-border);
-    border-radius: 2px;
+div.gridjs-download-btns button {
+    border-radius: 6px;
+    outline: 0;
+    -webkit-user-select: none;
+    -moz-user-select: none;
+    user-select: none;
     cursor: pointer;
+    margin-left: 10px;
 }
 
-div.dt-buttons {
-    margin-left: 0.5em;
+/* .gridjs-wrapper */
+.gridjs-wrapper.scrolled .gridjs-th-fixed {
+    background-color: #4f4f4f54;
+    z-index: 999;
+    outline: 1px solid var(--sn-color-table-border);
 }
 
-div.dt-buttons button {
-    padding: 0.1em 1em;
-    border: 1px solid var(--sn-color-datatable-btn-border);
-    border-radius: 2px;
-    font-size: 0.88em;
-    line-height: inherit;
+table thead.gridjs-thead th.gridjs-th {
+    padding: 8px;
+}
+
+th.gridjs-th .gridjs-th-content {
+    text-overflow: initial;
+    white-space: normal;
+    word-wrap: break-word;
+}
+
+button.gridjs-sort-neutral, button.gridjs-sort-asc, button.gridjs-sort-desc{
+    filter: brightness(0) saturate(100%) invert(40%) sepia(10%) saturate(366%) hue-rotate(182deg) brightness(94%) contrast(89%);
+}
+tbody.gridjs-tbody {
+    background-color: var(--sn-color-datatable-body-bg);
+}
+
+table tbody.gridjs-tbody td.gridjs-td {
+    padding: 8px;
+}
+/* .gridjs-footer */
+.gridjs-pagination {
     color: var(--sn-color-datatable-label);
-    white-space: nowrap;
-    overflow: hidden;
-    background-color: inherit;
-    background-image: none;
 }
 
-.dataTables_wrapper .dataTables_filter input {
-    max-width: 100px;
+.gridjs-pagination .gridjs-pages button {
+    background-color: var(--sn-color-datatable-body-bg);
+    color: var(--sn-color-datatable-label);
     border: 1px solid var(--sn-color-datatable-btn-border);
-    margin-bottom: 10px;
-    background-color: transparent;
-    border-radius: 2px;
+    padding: 8px;
+    border-right: none
 }
 
-.dataTables_wrapper.dataTables_wrapper .dataTables_length,
-.dataTables_wrapper.dataTables_wrapper .dataTables_filter,
-.dataTables_wrapper.dataTables_wrapper .dataTables_info,
-.dataTables_wrapper.dataTables_wrapper .dataTables_processing {
+.gridjs-pagination .gridjs-pages button:hover {
+    background-color: var(--sn-color-datatable-body-bg);
     color: var(--sn-color-datatable-label);
+    opacity: 0.7;
 }
 
-.dataTables_wrapper.dataTables_wrapper .dataTables_paginate,
-.dataTables_wrapper.dataTables_wrapper .dataTables_paginate a.paginate_button,
-.dataTables_wrapper.dataTables_wrapper .dataTables_paginate a.paginate_button.current {
-    /* datatables set this as !important, so unfortunately we have to do the same */
-    color: var(--sn-color-datatable-label) !important;
+.gridjs-pagination .gridjs-pages button:disabled, .gridjs-pagination .gridjs-pages button:hover:disabled, .gridjs-pagination .gridjs-pages button[disabled] {
+    background-color: var(--sn-color-datatable-body-bg);
+    filter: saturate(0.25);
+}
+.gridjs-pagination .gridjs-pages button.gridjs-currentPage {
+    background-color: var(--sn-color-datatable-body-bg);
+    color: var(--sn-color-datatable-label);
+    font-weight: bolder;
+}
+.gridjs-pagination .gridjs-pages button.gridjs-spread {
+    background-color: var(--sn-color-datatable-body-bg);
 }
 
-.dataTables_wrapper.dataTables_wrapper .dataTables_paginate a.paginate_button.disabled {
-    filter: saturate(0.5);
+.gridjs-pagination .gridjs-pages button:last-child {
+    border: 1px solid var(--sn-color-datatable-btn-border);
 }
 
-/* TODO: Ideally, if there is only one page, then the paginate buttons should be hidden. */
+/* Other GridJS style override */
+input.gridjs-input, div.gridjs-download-btns button {
+    background-color: var(--sn-color-datatable-body-bg);
+    color: var(--sn-color-datatable-label);
+    border: 1px solid var(--sn-color-datatable-btn-border);
+    padding: 8px;
+}

sphinx_needs/css/themes/blank.css

@@ -31,6 +31,7 @@
     --sn-color-datatable-body-bg: transparent;
     --sn-color-datatable-label: #333;
     --sn-color-datatable-btn-border: #999;
+    --sn-color-table-border: #a3a3a3;
 
     --sn-color-debug-btn-border: #333;
     --sn-color-debug-btn-on-text: #f43333;