Merge pull request #676 from DagsHub/bug/docs-build

Infra: Add GH action for docs build passing

Author: kbolashev

.github/workflows/docs-publish.yml

@@ -1,13 +1,16 @@
-name: Publish Docs
+name: Docs
 
 on:
   workflow_dispatch:
   release:
-    types: [published]
+    types: [ published ]
+  pull_request:
+    branches:
+      - main
 
 jobs:
-  deploy:
-
+  build:
+    name: Build documentation
     runs-on: ubuntu-latest
 
     defaults:
@@ -18,42 +21,58 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: "3.x"
+
       - name: Install client and dependencies
         working-directory: "./"
         run: |
           python -m pip install --upgrade pip setuptools
           pip install .
+
       - name: Install docs dependencies
         run: |
           pip install -r requirements-docs.txt
+
       - name: Build documentation
-        run: make html
+        run: SPHINXOPTS="-W" make html
 
-#      - name: Upload docs as artifact
-#        uses: actions/upload-artifact@v3
-#        with:
-#          name: docs
-#          path: docs/build
+      - 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
+
+  deploy:
+    name: Deploy documentation
+    needs: build
+    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-html
+          path: docs-html
 
       - name: Authenticate with Google
         uses: "google-github-actions/auth@v2"
         with:
           project_id: ${{ secrets.GCS_PROJECT }}
           credentials_json: ${{ secrets.GCS_SERVICE_ACCOUNT_ACCESS_KEY }}
 
-      - name: 'Set up Cloud SDK'
-        uses: 'google-github-actions/setup-gcloud@v2'
+      - name: Set up Cloud SDK
+        uses: "google-github-actions/setup-gcloud@v2"
 
       - name: Upload to Google Cloud Storage
         env:
           UPLOAD_PATH: ${{ format('gs://{0}/docs/client', secrets.DOCS_BUCKET) }}
-        run: gsutil -m rsync -d -r build/html $UPLOAD_PATH
+        run: gsutil -m rsync -d -r docs-html $UPLOAD_PATH
 
       - name: Invalidate CDN Cache
         env:
           LOAD_BALANCER: ${{ secrets.LOAD_BALANCER_NAME }}
         run: gcloud compute url-maps invalidate-cdn-cache $LOAD_BALANCER --async --path "/docs/client/*"
-

dagshub/common/cli.py

@@ -339,7 +339,7 @@ def create(ctx, repo_name, upload_data, clone, verbose, quiet):
     create a repo and optionally:
 
     - upload files to 'data' from a URL dir using `-u` flag. .zip and .tar files are extracted,
-    other formats copied as is.
+      other formats copied as is.
 
     - clone the repo locally using `--clone` flag
 

dagshub/data_engine/annotation/voxel_conversion.py

@@ -3,13 +3,14 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from dagshub.data_engine.client.models import Datapoint
-    import fiftyone as fo
+    import fiftyone
+
+    from dagshub.data_engine.model.datapoint import Datapoint
 
 logger = logging.getLogger(__name__)
 
 
-def add_voxel_annotations(sample: "fo.Sample", datapoint: "Datapoint", *annotation_fields: str):
+def add_voxel_annotations(sample: "fiftyone.Sample", datapoint: "Datapoint", *annotation_fields: str):
     """
     Adds annotation to the voxel sample.
 
@@ -26,7 +27,7 @@ def add_voxel_annotations(sample: "fo.Sample", datapoint: "Datapoint", *annotati
         sample.add_labels(label, label_field=field)
 
 
-def add_ls_annotations(sample: "fo.Sample", datapoint: "Datapoint", *annotation_fields: str):
+def add_ls_annotations(sample: "fiftyone.Sample", datapoint: "Datapoint", *annotation_fields: str):
     """
     Adds LabelStudio annotation to the voxel sample.
 
@@ -35,17 +36,17 @@ def add_ls_annotations(sample: "fo.Sample", datapoint: "Datapoint", *annotation_
         datapoint: Data Engine datapoint to get metadata from
         annotation_fields: fields from which to get annotations
     """
-    from fiftyone.utils.labelstudio import import_label_studio_annotation
     from fiftyone import (
-        Detections,
-        Detection,
         Classification,
         Classifications,
+        Detection,
+        Detections,
         Keypoint,
         Keypoints,
-        Polylines,
         Polyline,
+        Polylines,
     )
+    from fiftyone.utils.labelstudio import import_label_studio_annotation
 
     for field in annotation_fields:
         annotations = datapoint.metadata.get(field)

dagshub/data_engine/model/query.py

@@ -2,14 +2,13 @@
 import enum
 import logging
 import uuid
-from typing import Optional, Union, Dict
+from typing import Dict, Optional, Union
 
-import pytz
-from treelib import Tree, Node
+from treelib import Node, Tree
 
+from dagshub.data_engine.dtypes import MetadataFieldType
 from dagshub.data_engine.model.errors import WrongOperatorError
 from dagshub.data_engine.model.schema_util import metadata_type_lookup, metadata_type_lookup_reverse
-from dagshub.data_engine.dtypes import MetadataFieldType
 
 logger = logging.getLogger(__name__)
 
@@ -24,7 +23,7 @@ def bytes_deserializer(val: str) -> bytes:
 _metadataTypeCustomConverters = {
     bool: lambda x: x.lower() == "true",
     bytes: bytes_deserializer,
-    datetime.datetime: lambda x: datetime.datetime.fromtimestamp(int(x) / 1000).astimezone(pytz.utc),
+    datetime.datetime: lambda x: datetime.datetime.fromtimestamp(int(x) / 1000, tz=datetime.timezone.utc),
 }
 
 

docs/Makefile

@@ -18,7 +18,7 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) --exception-on-warning -W
 
 serve:
-	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) --watch "$(CODEDIR)" $(O)
+	sphinx-autobuild -W "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) --watch "$(CODEDIR)" $(O)

docs/requirements-docs.txt

@@ -1,7 +1,7 @@
-sphinx==7.3.7
-furo==2024.5.6
-sphinx-autobuild==2024.4.16
+sphinx==9.1.0
+furo==2025.12.19
+sphinx-autobuild==2025.8.25
 sphinx-copybutton==0.5.2
-sphinx-sitemap==2.6.0
-sphinx-click==5.0.1
-sphinx-autodoc-typehints==2.3.0
+sphinx-sitemap==2.9.0
+sphinx-click==6.2.0
+sphinx-autodoc-typehints==3.9.9

docs/source/conf.py

@@ -8,12 +8,19 @@
 
 import os
 import sys
+import types
+from datetime import datetime
 
 project_root = os.path.join(__file__, "../../..")
 sys.path.insert(0, os.path.abspath(project_root))
 
+# Fix for is_mlflow_installed reading the spec of the module that is not imported in the doc build environment
+_env_mod = types.ModuleType("dagshub.common.environment")
+_env_mod.is_mlflow_installed = False
+sys.modules["dagshub.common.environment"] = _env_mod
+
 project = "DagsHub Client"
-copyright = "2023, DagsHub"
+copyright = f"{datetime.now().year}, DagsHub"
 author = "DagsHub"
 
 # -- General configuration ---------------------------------------------------

docs/source/reference/metric_logging.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Metric Logging (``dagshub.logger``)
 ====================================