docs: adding initial mkdocs structure

.github/workflows/build_docs.yml

@@ -0,0 +1,19 @@
+name: build_docs
+# Disable for now while the repo is private
+# on:
+#   push:
+#     branches:
+#       - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v2
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.9.5"
+      - run: uv python install
+      - run: uv sync --group docs
+      - run: uv run mkdocs gh-deploy --force --clean --verbose

Makefile

@@ -35,6 +35,7 @@ help:
 	@echo ""
 	@echo "🛠️  Utilities:"
 	@echo "  clean                  - Remove coverage reports and cache files"
+	@echo "  serve-docs-locally     - Serve documentation locally
 	@echo "  check-license-headers  - Check if all files have license headers"
 	@echo "  update-license-headers - Add license headers to all files"
 	@echo ""
@@ -82,6 +83,11 @@ test:
 	@echo "🧪 Running unit tests..."
 	uv run --group dev pytest
 
+serve-docs-locally:
+	@echo "📝 Building and serving docs..."
+	uv sync --group docs
+	uv run mkdocs serve
+
 check-license-headers:
 	@echo "🔍 Checking license headers in all files..."
 	uv run python $(REPO_PATH)/scripts/update_license_headers.py --check

docs/css/code_select.css

@@ -0,0 +1,3 @@
+.highlight .gp, .highlight .go { /* Generic.Prompt, Generic.Output */
+    user-select: none;
+}

docs/index.md

@@ -0,0 +1,3 @@
+# Data Designer
+
+Welcome to the Data Designer documentation.

mkdocs.yml

@@ -0,0 +1,21 @@
+site_name: Data Designer
+theme:
+  name: material
+plugins:
+  - search
+  - gen-files:
+      scripts:
+        - scripts/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          filters: "!^(__.*__$)"
+nav:
+  - Welcome: index.md
+  - Code Reference: reference/
+extra_css:
+- css/code_select.css

pyproject.toml

@@ -61,6 +61,15 @@ dev = [
   "pytest-cov>=7.0.0",
   "pytest-httpx>=0.35.0",
 ]
+docs = [
+  "mkdocs>=1.6.1",
+  "mkdocstrings>=0.30.1",
+  "mkdocstrings-python>=1.18.2",
+  "mkdocs-gen-files>=0.5.0",
+  "mkdocs-literate-nav>=0.6.2",
+  "mkdocs-section-index>=0.3.10",
+  "mkdocs-material>=9.6.22",
+]
 notebooks = [
   "jupyter>=1.0.0",
   "ipykernel>=6.29.0",

scripts/gen_ref_pages.py

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import griffe
+import mkdocs_gen_files
+
+data = griffe.load("data_designer")
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent
+src = root / "src"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__main__":
+        continue
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+
+        init_module = data[parts[1:]] if len(parts) > 1 else data
+        has_docstrings = init_module.has_docstring or any(
+            member.has_docstrings
+            for member in init_module.members.values()
+            if not (member.is_alias or member.is_module)
+        )
+    else:
+        has_docstrings = data[parts[1:]].has_docstrings
+
+    if not has_docstrings:
+        continue
+
+    nav[parts] = doc_path.as_posix()
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

src/data_designer/config/analysis/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/config/analysis/utils/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/config/utils/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/analysis/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/analysis/column_profilers/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/analysis/reporting/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/analysis/utils/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/column_generators/utils/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/dataset_builders/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/models/recipes/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/processing/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/processing/processors/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/registry/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/resources/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/sampling_gen/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+

src/data_designer/engine/sampling_gen/data_sources/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+