OpenTabular · mkumar73 · May 8, 2026 · May 8, 2026 · May 8, 2026 · May 8, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,30 @@ Going forward, this file is updated automatically by `cz bump` on each release.
 
 ---
 
+## v1.7.0rc1 (2026-05-08)
+
+### Documentation
+
+- Added **Developer Guide** section with dedicated pages for contributing, the release process, model promotion policy (experimental → stable), and a SPEC 0–aligned support matrix
+- Added **Getting Started** section: new Overview page with full model reference table, Installation guide (prerequisites, PyPI, source, optional Mamba CUDA kernels), and Key Concepts page covering the sklearn API, task variants, config system, and preprocessing
+- Rewrote all three example pages (classification, regression, distributional regression) as narrative tutorials with runnable code and "using your own data" sections
+- Added `llms.txt` index for LLM tool discovery
+- Switched to `sphinx_design` for cards and grid layouts; added custom CSS with JetBrains Mono font and brand colour palette
+- Added `pygments_style = "friendly"` and dark-mode code block colours via CSS
+
+### CI
+
+- Dropped Python 3.14 from the test matrix (`scipy` wheels are not yet available); ceiling reverted to `<3.14` in `pyproject.toml`
+- Fixed `torch` upper bound from `<=2.7.0` to `<2.8.0` to allow patch releases
+- Added Lightning log filtering to reduce test output noise
+- Regenerated `poetry.lock` after dependency constraint changes
+
+### Bug Fixes
+
+- Fixed Pyright type errors in test fixtures (DataFrame construction and unused variable bindings)
+
+---
+
 ## v1.6.1 (2025-04-26)
 
 ### Changes

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -19,42 +19,152 @@ html[data-theme="dark"] {
   --pst-color-link: #38bdf8;
 }
 
-/* Dark mode: code block background and text */
+/* ── Code blocks: GitHub light (default) + GitHub dark (dark mode) ─────────── */
+
+/* Light mode — GitHub light palette */
+div.highlight,
+.highlight pre {
+  background: #f6f8fa;
+  color: #24292f;
+}
+.highlight pre span {
+  color: #24292f;
+}
+.highlight .k,
+.highlight .kn,
+.highlight .kd,
+.highlight .kr,
+.highlight .kc {
+  color: #cf222e;
+  font-weight: 500;
+}
+.highlight .s,
+.highlight .s1,
+.highlight .s2,
+.highlight .sa,
+.highlight .sb,
+.highlight .sc,
+.highlight .sd,
+.highlight .se,
+.highlight .si,
+.highlight .sh {
+  color: #0a3069;
+}
+.highlight .mi,
+.highlight .mf,
+.highlight .mh,
+.highlight .mo {
+  color: #0550ae;
+}
+.highlight .nf,
+.highlight .fm {
+  color: #6639ba;
+}
+.highlight .nc {
+  color: #953800;
+  font-weight: 500;
+}
+.highlight .nd {
+  color: #953800;
+}
+.highlight .nb,
+.highlight .bp {
+  color: #0550ae;
+}
+.highlight .nn {
+  color: #24292f;
+}
+.highlight .o,
+.highlight .ow {
+  color: #cf222e;
+}
+.highlight .c,
+.highlight .c1,
+.highlight .cm,
+.highlight .cs,
+.highlight .cp {
+  color: #6e7781;
+  font-style: italic;
+}
+.highlight .n,
+.highlight .na,
+.highlight .nv,
+.highlight .py {
+  color: #24292f;
+}
+.highlight .p {
+  color: #24292f;
+}
+
+/* Dark mode — GitHub dark palette */
 html[data-theme="dark"] div.highlight,
 html[data-theme="dark"] .highlight pre {
-  background: #1e2433;
-  color: #abb2bf;
+  background: #0d1117 !important;
+  color: #e6edf3 !important;
+}
+html[data-theme="dark"] .highlight pre span {
+  color: #e6edf3;
+}
+html[data-theme="dark"] .highlight .k,
+html[data-theme="dark"] .highlight .kn,
+html[data-theme="dark"] .highlight .kd,
+html[data-theme="dark"] .highlight .kr,
+html[data-theme="dark"] .highlight .kc {
+  color: #ff7b72;
+  font-weight: 500;
 }
-
-html[data-theme="dark"] .highlight .k {
-  color: #c678dd;
-} /* keyword */
 html[data-theme="dark"] .highlight .s,
 html[data-theme="dark"] .highlight .s1,
-html[data-theme="dark"] .highlight .s2 {
-  color: #98c379;
-} /* string */
-html[data-theme="dark"] .highlight .c,
-html[data-theme="dark"] .highlight .c1 {
-  color: #5c6370;
-  font-style: italic;
-} /* comment */
+html[data-theme="dark"] .highlight .s2,
+html[data-theme="dark"] .highlight .sa,
+html[data-theme="dark"] .highlight .se,
+html[data-theme="dark"] .highlight .si,
+html[data-theme="dark"] .highlight .sh {
+  color: #a5d6ff;
+}
 html[data-theme="dark"] .highlight .mi,
-html[data-theme="dark"] .highlight .mf {
-  color: #d19a66;
-} /* number */
-html[data-theme="dark"] .highlight .nf {
-  color: #61afef;
-} /* function name */
+html[data-theme="dark"] .highlight .mf,
+html[data-theme="dark"] .highlight .mh {
+  color: #79c0ff;
+}
+html[data-theme="dark"] .highlight .nf,
+html[data-theme="dark"] .highlight .fm {
+  color: #d2a8ff;
+}
 html[data-theme="dark"] .highlight .nc {
-  color: #e5c07b;
-} /* class name */
-html[data-theme="dark"] .highlight .kn {
-  color: #c678dd;
-} /* import keyword */
+  color: #ffa657;
+  font-weight: 500;
+}
+html[data-theme="dark"] .highlight .nd {
+  color: #ffa657;
+}
+html[data-theme="dark"] .highlight .nb,
+html[data-theme="dark"] .highlight .bp {
+  color: #79c0ff;
+}
 html[data-theme="dark"] .highlight .nn {
-  color: #e5c07b;
-} /* module name */
+  color: #e6edf3;
+}
+html[data-theme="dark"] .highlight .o,
+html[data-theme="dark"] .highlight .ow {
+  color: #ff7b72;
+}
+html[data-theme="dark"] .highlight .c,
+html[data-theme="dark"] .highlight .c1,
+html[data-theme="dark"] .highlight .cm,
+html[data-theme="dark"] .highlight .cp {
+  color: #8b949e;
+  font-style: italic;
+}
+html[data-theme="dark"] .highlight .n,
+html[data-theme="dark"] .highlight .na,
+html[data-theme="dark"] .highlight .nv,
+html[data-theme="dark"] .highlight .py {
+  color: #e6edf3;
+}
+html[data-theme="dark"] .highlight .p {
+  color: #e6edf3;
+}
 
 .bd-main .bd-content .bd-article-container {
   max-width: 900px;
@@ -110,3 +220,68 @@ div.highlight {
   box-shadow: none;
   border-bottom: 1px solid var(--pst-color-border);
 }
+
+/* Page title (h1): visually similar to h2 to reduce dominance */
+.bd-article h1 {
+  font-size: 1.75rem;
+  font-weight: 700;
+  line-height: 1.3;
+}
+
+.bd-article h2 {
+  font-size: 1.4rem;
+  font-weight: 600;
+  line-height: 1.35;
+}
+
+.bd-article h3 {
+  font-size: 1.15rem;
+  font-weight: 600;
+  line-height: 1.4;
+}
+
+.bd-article h4 {
+  font-size: 1rem;
+  font-weight: 600;
+  line-height: 1.4;
+}
+
+/* ── Sidebar nav section separators ───────────────────────────────────────── */
+/* Each top-level toctree becomes a <ul class="bd-sidenav"> inside
+   .bd-sidebar-primary .sidebar-primary-items__start nav.
+   We insert a thin rule above each group except the first. */
+.bd-sidebar-primary .bd-toc ul.current > li.toctree-l1:first-child,
+.bd-sidebar-primary nav.bd-sidenav > ul > li {
+  /* no rule needed here */
+}
+
+/* Target the caption elements (section titles like "Getting Started") */
+.bd-sidebar-primary .caption-text {
+  font-size: 0.7rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--pst-color-text-muted);
+  padding-top: 0.75rem;
+  margin-top: 0.5rem;
+  border-top: 1px solid var(--pst-color-border);
+  display: block;
+}
+
+/* Remove the border-top from the very first caption */
+.bd-sidebar-primary .toctree-wrapper > ul > li:first-child .caption-text,
+.bd-sidebar-primary nav > ul > li.has-children:first-child > .caption-text {
+  border-top: none;
+  padding-top: 0;
+  margin-top: 0;
+}
+
+/* ── Navbar: GitHub icon + text label ─────────────────────────────────────── */
+/* pydata-sphinx-theme hides .icon-link-name by default; reveal it */
+.navbar-icon-link .icon-link-name {
+  display: inline !important;
+  font-size: 0.85rem;
+  font-weight: 500;
+  margin-left: 0.3rem;
+  vertical-align: middle;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -48,6 +48,7 @@
     "myst_parser",
     "mdinclude",  # custom module
     "sphinx_rtd_theme",
+    "sphinxcontrib.mermaid",
     # "pydata_sphinx_theme",
     "sphinx_autodoc_typehints",
     "sphinx_design",
@@ -105,7 +106,7 @@
 show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "friendly"
+pygments_style = "github-light"
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -120,8 +121,8 @@
     "repository_url": "https://github.com/OpenTabular/DeepTab",
     "repository_branch": "main",
     "path_to_docs": "docs",
-    "use_edit_page_button": True,
-    "use_source_button": True,
+    "use_edit_page_button": False,
+    "use_source_button": False,
     "show_toc_level": 2,
     "navigation_with_keys": True,
     "show_prev_next": True,

diff --git a/docs/developer_guide/release.md b/docs/developer_guide/release.md
@@ -2,6 +2,43 @@
 
 The document outlines the steps to build and release the `deeptab` package. At this point, it is assumed that the development and testing of the package have been completed successfully.
 
+## Release workflow
+
+```{mermaid}
+%%{init: {'theme': 'base', 'themeVariables': {
+  'primaryColor': '#dbeafe',
+  'primaryTextColor': '#1e3a5f',
+  'primaryBorderColor': '#3b82f6',
+  'lineColor': '#6b7280',
+  'secondaryColor': '#ede9fe',
+  'tertiaryColor': '#f0fdf4',
+  'edgeLabelBackground': '#f9fafb'
+}}}%%
+flowchart TD
+    A[Create release/vX.Y.Z branch]:::setup --> B[Bump version]:::setup
+    B --> C[Update CHANGELOG.md]:::setup
+    C --> D[Commit & push branch]:::setup
+    D --> E[Open PR: release/vX.Y.Z → main]:::pr
+    E --> F{Review & approve}:::decision
+    F --> G[Merge PR into main]:::pr
+    G --> H[git checkout main && git pull]:::git
+    H --> I{Release type?}:::decision
+    I -->|RC| J["git tag vX.Y.ZrcN\ngit push origin vX.Y.ZrcN"]:::git
+    I -->|Stable| K["git tag vX.Y.Z\ngit push origin vX.Y.Z"]:::git
+    J --> L[CI: publish-testpypi.yml]:::ci
+    K --> M[CI: publish-pypi.yml]:::ci
+    L --> N[TestPyPI + GitHub pre-release]:::rc
+    M --> O[PyPI + GitHub Release]:::stable
+
+    classDef setup  fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
+    classDef pr     fill:#ede9fe,stroke:#8b5cf6,color:#3b0764
+    classDef decision fill:#fef9c3,stroke:#ca8a04,color:#713f12
+    classDef git    fill:#f0fdf4,stroke:#22c55e,color:#14532d
+    classDef ci     fill:#fff7ed,stroke:#f97316,color:#7c2d12
+    classDef rc     fill:#fdf4ff,stroke:#d946ef,color:#701a75
+    classDef stable fill:#ecfdf5,stroke:#10b981,color:#064e3b
+```
+
 ## 1. Test documentation
 
 It is expected from the contributor to update the documentation as an when required along side the change in source code. Please use the below process to test the documentation:
@@ -18,7 +55,9 @@ Fix any docstring related issue, then proceed with next steps.
 
 The package version is maintained in `pyproject.toml` only. The version is read at runtime via `importlib.metadata`.
 
-On a `release/vX.Y.Z` branch, run:
+On a `release/vX.Y.Z` branch:
+
+**For a stable release** — let `cz bump` derive the next version automatically from conventional commits:
 
 ```bash
 cz bump
@@ -31,7 +70,21 @@ This will:
 - Update `CHANGELOG.md`
 - Create a local commit `bump: version X.Y.Z-1 → X.Y.Z`
 
-The version number follows the format `major.minor.patch`. For example, `1.0.1`.
+**For a release candidate** — set the version explicitly (e.g. `1.7.0rc1`):
+
+```bash
+poetry version 1.7.0rc1
+poetry lock
+```
+
+Then update `CHANGELOG.md` manually and commit:
+
+```bash
+git add pyproject.toml poetry.lock CHANGELOG.md
+git commit -m "bump: version 1.6.1 → 1.7.0rc1"
+```
+
+The version number follows the format `major.minor.patch` for stable, or `major.minor.patchrcN` for release candidates.
 
 ## 3. Release PR
 

diff --git a/docs/requirements_docs.txt b/docs/requirements_docs.txt
@@ -15,3 +15,4 @@ readthedocs-sphinx-ext==2.2.5
 lxml-html-clean==0.4.0
 pydata-sphinx-theme==0.15.2
 sphinx-design
+sphinxcontrib-mermaid