ci: add dedicated docs workflow, fix RTD build config

Co-authored-by: Copilot <copilot@github.com>

Author: mkumar73

.github/workflows/ci.yml

@@ -2,6 +2,9 @@ name: CI
 
 on:
   workflow_dispatch:
+  push:
+    branches:
+      - main
   pull_request:
     branches:
       - main

.github/workflows/docs.yml

@@ -0,0 +1,69 @@
+name: Docs
+
+on:
+  workflow_dispatch:
+  pull_request:
+    # Only run on PRs that touch docs-related files to keep checks fast.
+    paths:
+      - "docs/**"
+      - "README.md"
+      - "pyproject.toml"
+      - "deeptab/**"
+  push:
+    # No paths filter here: tag pushes must always build docs regardless of
+    # which files changed in the tagged commit. Paths filters in GitHub Actions
+    # apply to both branches and tags under the same push: block, so a tag
+    # like v1.7.0 would be silently skipped if docs files weren't in that commit.
+    branches:
+      - main
+    tags:
+      - "v*"
+
+concurrency:
+  group: docs-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    name: Build docs (Sphinx)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y pandoc
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: "poetry"
+
+      - name: Install package
+        run: poetry install --only main
+
+      - name: Install docs dependencies
+        run: pip install -r docs/requirements_docs.txt
+
+      - name: Build Sphinx docs
+        run: poetry run sphinx-build -b html docs/ docs/_build/html -W --keep-going
+
+      # ── Triggered on push to main ──────────────────────────────────────────
+      # RTD listens to its own webhook and publishes "latest" automatically.
+      # The step below is informational; actual publishing is done by RTD.
+      - name: Notify latest/dev docs will be published
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: echo "Docs build succeeded. RTD will publish the 'latest' version."
+
+      # ── Triggered on a release tag ─────────────────────────────────────────
+      # RTD listens to tag pushes and publishes a versioned snapshot automatically
+      # when "Build tags" is enabled in the RTD project settings.
+      - name: Notify stable/versioned docs will be published
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          echo "Docs build succeeded for tag ${TAG}. RTD will publish the '${TAG}' versioned docs."

pyproject.toml

@@ -39,6 +39,23 @@ commitizen = "^3.29.1"
 twine = "^6.2.0"
 pyright = "^1.1.409"
 
+[tool.poetry.group.docs.dependencies]
+setuptools = "*"
+sphinx = "6.2.1"
+sphinx-autodoc-typehints = "1.23.0"
+numpydoc = "1.7.0"
+nbsphinx = "0.9.4"
+ipython = "*"
+myst-parser = "3.0.1"
+m2r2 = "0.3.3.post2"
+sphinx-copybutton = "0.5.2"
+sphinx-togglebutton = "0.3.2"
+sphinx-book-theme = "1.1.2"
+sphinx-rtd-theme = "2.0.0"
+readthedocs-sphinx-ext = "2.2.5"
+lxml-html-clean = "0.4.0"
+pydata-sphinx-theme = "0.15.2"
+
 
 [tool.poetry.urls]
 homepage = "https://github.com/OpenTabular/deeptab"

readthedocs.yaml

@@ -29,4 +29,7 @@ formats:
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
+    - method: pip
+      path: .
+      extra_requirements: []
     - requirements: docs/requirements_docs.txt