Infra: Add GH action for docs build passing

[kbolashev]

This should prevent problems with sections disappearing from documentation.

[dagshub]

Join the discussion on DagsHub!

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

GitHub Actions workflow renamed and split into build (produces docs-html artifact) and deploy (downloads artifact and rsyncs to GCS); pull_request trigger added for main; action versions bumped. Docs build made warnings-as-errors; small runtime and typing tweaks in code (removed pytz, annotations updated).

Changes

Cohort / File(s)	Summary
Docs CI Workflow .github/workflows/docs-publish.yml	Renamed workflow to Docs; added pull_request trigger for main; split into build (runs on workflow_dispatch/release, runs SPHINXOPTS="-W" make html, uploads docs-html artifact) and deploy (depends on build, downloads docs-html, runs gsutil ... rsync); bumped action versions and minor step quoting changes.
Documentation build/config docs/Makefile, docs/requirements-docs.txt, docs/source/conf.py, docs/source/reference/metric_logging.rst	Made Sphinx treat warnings as errors (-W, --exception-on-warning); bumped doc deps; injected synthetic dagshub.common.environment module in conf to avoid runtime import during build; added :orphan: directive.
Core code & typing tweaks dagshub/data_engine/model/query.py, dagshub/data_engine/annotation/voxel_conversion.py, dagshub/common/cli.py	Replaced pytz usage with datetime.timezone.utc for timestamp deserialization; consolidated typing imports; updated fiftyone type annotations and import ordering; adjusted help-text indentation only in CLI.

Sequence Diagram(s)

sequenceDiagram
    participant GH as GitHub Actions
    participant Runner as Workflow Runner
    participant Artif as Artifact Storage
    participant GCS as Google Cloud Storage

    GH->>Runner: trigger (workflow_dispatch / release / pull_request on main)
    Runner->>Runner: run build job\nSPHINXOPTS="-W" make html
    Runner->>Artif: upload `docs-html` artifact
    Runner->>Runner: start deploy job (depends on build)
    Runner->>Artif: download `docs-html` artifact
    Runner->>GCS: gsutil rsync ./docs-html/ gs://<bucket>/path

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through YAML, neat and spry,

Split the jobs so docs could fly,
Built with warnings held up high,
Packaged pages, sent them nigh,
A cloudbound hop beneath the sky.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title specifically references adding a GitHub action for docs build passing, which aligns with the workflow refactoring and CI/CD improvements shown in .github/workflows/docs-publish.yml.
Description check	✅ Passed	The description relates to preventing documentation sections from disappearing, which aligns with the docs build improvements, stricter Sphinx warnings handling, and dependency updates throughout the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch bug/docs-build

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Adds a CI guardrail to ensure the Sphinx documentation successfully builds on every PR to main, helping catch documentation regressions (e.g., missing/invalid sections) before merge.

Changes:

• Introduces a new GitHub Actions workflow to build Sphinx docs on pull_request to main.
• Installs the project package plus docs/requirements-docs.txt dependencies before running make html with warnings treated as errors (SPHINXOPTS="-W").

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 281435e3-70e9-40f6-8c3f-3c9958408fd3

📥 Commits

Reviewing files that changed from the base of the PR and between 65e9f6a and c84f203.

📒 Files selected for processing (1)

• .github/workflows/docs-build-check.yml

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)

• GitHub Check: Agent
• GitHub Check: build (3.10)
• GitHub Check: build (3.9)
• GitHub Check: build (3.13)
• GitHub Check: build (3.11)
• GitHub Check: build (3.12)

🧰 Additional context used

🪛 actionlint (1.7.11)

.github/workflows/docs-build-check.yml

[error] 21-21: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue

(action)

[coderabbitai]

🧹 Nitpick comments (1)

.github/workflows/docs-publish.yml (1)

41-46: Add if-no-files-found: error to fail fast if artifact path is missing.

The default behavior (warn) allows the workflow to continue even if the docs build directory is absent, deferring failure to the deploy stage. Use error to catch the issue immediately in the build job.

♻️ Proposed change

       - name: Upload build artifact
         if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
         uses: actions/upload-artifact@v4
         with:
           name: docs-html
           path: docs/build/html
+          if-no-files-found: error

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4869f10d-12f6-4542-a8cf-2aef12ffa411

📥 Commits

Reviewing files that changed from the base of the PR and between c84f203 and 32b3cd1.

📒 Files selected for processing (1)

• .github/workflows/docs-publish.yml

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: build (3.10)
• GitHub Check: build (3.12)
• GitHub Check: build (3.9)

🔇 Additional comments (2)

.github/workflows/docs-publish.yml (2)

7-9: Good separation of validation vs deployment paths.

Running build on pull_request while keeping deploy gated to release/workflow_dispatch cleanly enforces docs build health without accidental publishing.

Also applies to: 12-13, 48-52

---

38-39: Strict Sphinx warning handling is a strong quality gate.

Using SPHINXOPTS="-W" is the right move for catching doc regressions early.

[coderabbitai]

🧹 Nitpick comments (1)

docs/Makefile (1)

20-21: Remove redundant warning-as-error flags.

Both -W and --exception-on-warning cause Sphinx to treat warnings as errors. Since the project uses Sphinx 9.1.0, both are supported, but using both is redundant. Choose one:

• Use just -W (simpler, shorter syntax)
• Use just --exception-on-warning (explicit intent)

If CI already passes SPHINXOPTS="-W", the hardcoded flags here add another layer of redundancy.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8067f4d0-f422-436c-bc16-ea1930a0e4c1

📥 Commits

Reviewing files that changed from the base of the PR and between 8044e1b and 93fb3e6.

📒 Files selected for processing (6)

• dagshub/common/cli.py
• dagshub/data_engine/annotation/voxel_conversion.py
• docs/Makefile
• docs/requirements-docs.txt
• docs/source/conf.py
• docs/source/reference/metric_logging.rst

✅ Files skipped from review due to trivial changes (4)

• docs/source/reference/metric_logging.rst
• dagshub/common/cli.py
• docs/requirements-docs.txt
• dagshub/data_engine/annotation/voxel_conversion.py

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: build (3.13)
• GitHub Check: build (3.10)
• GitHub Check: build (3.9)
• GitHub Check: build (3.11)
• GitHub Check: build (3.12)

🧰 Additional context used

🧬 Code graph analysis (1)

docs/source/conf.py (1)

dagshub/streaming/filesystem.py (1)

• path (1119-1124)

🪛 Ruff (0.15.6)

docs/source/conf.py

[error] 22-22: Variable copyright is shadowing a Python builtin

(A001)

🔇 Additional comments (4)

docs/source/conf.py (3)

11-11: LGTM!

The types import is correctly added for creating the synthetic module below.

---

16-19: LGTM!

Good fix for the doc build environment. The synthetic module injection is correctly placed before any project imports would occur, and the comment explains the intent well.

Minor note: if other attributes from dagshub.common.environment are accessed during doc builds, they may raise AttributeError. This should be acceptable for current usage, but keep in mind if future doc build issues arise.

---

22-22: LGTM!

Copyright year correctly updated.

Regarding the static analysis hint about shadowing the copyright builtin: this is expected and intentional. copyright is a standard Sphinx configuration variable name, and this pattern exists in all Sphinx conf.py files. The warning can be safely ignored.

docs/Makefile (1)

23-24: LGTM!

Using -W for sphinx-autobuild is appropriate and ensures consistent warnings-as-errors behavior during local development.