Merge pull request #145 from amikos-tech/feature/documentation-site

Phase 6: Documentation Site

Author: oss-amikos

.github/workflows/docs.yml

@@ -0,0 +1,79 @@
+name: docs
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+
+      - name: Install MkDocs dependencies
+        run: |
+          python -m venv .venv
+          . .venv/bin/activate
+          python -m pip install -r docs/requirements.txt
+
+      - name: Build MkDocs site
+        run: |
+          . .venv/bin/activate
+          python -m mkdocs build --config-file docs/mkdocs.yml --site-dir site
+
+      - uses: actions/setup-java@v4
+        with:
+          java-version: '8'
+          distribution: 'temurin'
+          cache: maven
+
+      - name: Generate Javadoc
+        run: mvn --no-transfer-progress compile javadoc:javadoc
+
+      - name: Merge Javadoc into site
+        run: |
+          mkdir -p site/api
+          cp -R target/site/apidocs/. site/api/
+
+      - name: Upload site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: site
+          if-no-files-found: error
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download site artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs-site
+          path: site
+
+      - name: Deploy combined docs site
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site

.gitignore

@@ -57,3 +57,9 @@ fabric.properties
 .idea/httpRequests
 .idea/caches/build_file_checksums.ser
 **.env
+
+### Claude Code ###
+.claude/worktrees/
+
+### MkDocs ###
+docs/site/

.planning/PROJECT.md

@@ -61,4 +61,4 @@ The repository already contains substantial v2 implementation under `src/main/ja
 | Keep Java 8 + synchronous API as hard constraints for this milestone | Minimizes adoption friction and migration risk | — Pending |
 
 ---
-*Last updated: 2026-03-20 — Phase 1 complete (ERGO-01, ERGO-02). Row-based result access and WhereDocument DSL shipped. Next: Phase 2 (Collection API Extensions).*
+*Last updated: 2026-03-25 — Phase 6 complete (DOC-01 through DOC-06). Documentation site with 12 guide pages, MkDocs Material theme, CI deployment, and Javadoc integration shipped. Next: Phase 7 (Working Examples).*

.planning/ROADMAP.md

@@ -17,8 +17,11 @@ Decimal phases appear between their surrounding integers in numeric order.
 - [x] **Phase 3: Search API** — Implement the Search endpoint with ranking expressions, field projection, groupBy, and read levels. (completed 2026-03-22)
 - [ ] **Phase 4: Embedding Ecosystem** — Add sparse/multimodal interfaces, reranking, new providers, and embedding registry.
 - [ ] **Phase 5: Cloud Integration Testing** — Build cloud parity test suites for search, schema/index, and array metadata. (gap closure in progress)
-- [ ] **Phase 6: Documentation Site** — Build a rich documentation site with API surfaces, examples, and feature guides (similar to chroma-go docs).
+- [x] **Phase 6: Documentation Site** — Build a rich documentation site with API surfaces, examples, and feature guides (similar to chroma-go docs). (completed 2026-03-24)
 - [ ] **Phase 7: Working Examples** — Add full working examples for all major features (similar to chroma-go examples/).
+- [ ] **Phase 8: API DX Improvements** — Add Consumer lambda overloads for collection creation and Schema convenience factories (#143, #144).
+- [ ] **Phase 9: Logging Bridges** — Implement SLF4J and JUL bridges for ChromaLogger (#141, #142).
+- [ ] **Phase 10: Documentation Update** — Refresh docs site with DX improvements, logging bridges, and any API changes from Phases 8-9.
 
 ## Phase Details
 
@@ -118,13 +121,23 @@ Phase 4 can execute in parallel with Phases 1-3 (independent).
 
 ### Phase 6: Documentation Site
 
-**Goal:** Build a rich documentation site (similar to amikos-tech/chroma-go) covering all library features, API surfaces, and usage examples.
-**Requirements**: TBD
+**Goal:** Build a rich documentation site (similar to amikos-tech/chroma-go) covering all library features, API surfaces, and usage examples, deployed to java.chromadb.dev via GitHub Pages.
+**Requirements**: [DOC-01, DOC-02, DOC-03, DOC-04, DOC-05, DOC-06]
 **Depends on:** Phases 1-5 (documents features built in earlier phases)
-**Plans:** 0 plans
+**Success Criteria** (what must be TRUE):
+  1. MkDocs Material site builds with `--strict` flag without errors.
+  2. All 12 guide pages have rich content with snippet-included Java code examples (v2 API only).
+  3. GitHub Actions workflow deploys MkDocs + Javadoc to GitHub Pages on push to main.
+  4. Custom domain java.chromadb.dev configured via CNAME file.
+  5. Examples section stubbed with 7 topic directories for Phase 7.
+  6. User visually approves the site via local `mkdocs serve`.
+**Plans:** 4/4 plans complete
 
 Plans:
-- [ ] TBD (run /gsd:plan-phase 6 to break down)
+- [x] 06-01-PLAN.md — MkDocs scaffold, config, homepage, CI workflow, Javadoc plugin upgrade
+- [x] 06-02-PLAN.md — Core guide pages (client, auth, records, filtering, search, embeddings) with snippet files
+- [x] 06-03-PLAN.md — Advanced guide pages (cloud-features, schema, id-generators, transport, logging, migration) with snippet files
+- [x] 06-04-PLAN.md — Examples section stubs, nav expansion, and visual verification checkpoint
 
 ### Phase 7: Working Examples
 
@@ -135,3 +148,50 @@ Plans:
 
 Plans:
 - [ ] TBD (run /gsd:plan-phase 7 to break down)
+
+### Phase 8: API DX Improvements
+
+**Goal:** Reduce builder boilerplate in the most common API paths — collection creation gets Consumer lambda overloads, and Schema gets mid-level factory methods to flatten deep nesting.
+**Requirements**: TBD
+**Depends on:** Phase 6 (docs merged first)
+**Issues:** #143, #144
+**Success Criteria** (what must be TRUE):
+  1. User can call `client.getOrCreateCollection("name", opts -> opts.embeddingFunction(ef))` without explicit `.builder()/.build()`.
+  2. User can create a common HNSW schema with a single factory method instead of 5 nested builders.
+  3. Existing `.builder().build()` API remains unchanged for backwards compatibility.
+  4. All new overloads have unit tests.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 8 to break down)
+
+### Phase 9: Logging Bridges
+
+**Goal:** Provide out-of-the-box ChromaLogger implementations for SLF4J (covers Logback) and java.util.logging so users get transport-level logging without writing their own bridge.
+**Requirements**: TBD
+**Depends on:** Nothing (independent)
+**Issues:** #141, #142
+**Success Criteria** (what must be TRUE):
+  1. `Slf4jChromaLogger.create()` routes ChromaLogger events to SLF4J with structured fields.
+  2. `JulChromaLogger.create()` routes ChromaLogger events to java.util.logging.
+  3. SLF4J is an optional/provided dependency (not pulled transitively).
+  4. Both bridges have unit tests.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 9 to break down)
+
+### Phase 10: Documentation Update
+
+**Goal:** Refresh the documentation site with new API patterns from Phases 8-9 — Consumer overloads, Schema factories, logging bridge usage — and incorporate any corrections from user feedback.
+**Requirements**: TBD
+**Depends on:** Phases 8, 9
+**Success Criteria** (what must be TRUE):
+  1. Guide pages updated with Consumer lambda examples alongside existing builder examples.
+  2. Logging page updated with SLF4J and JUL bridge usage examples.
+  3. Schema page updated with convenience factory examples.
+  4. `mkdocs build --strict` passes.
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 10 to break down)

.planning/STATE.md

@@ -2,14 +2,14 @@
 gsd_state_version: 1.0
 milestone: v1.5
 milestone_name: milestone
-status: "Phase 05 shipped — PR #140"
-stopped_at: Completed 05-cloud-integration-testing-05-03-PLAN.md
-last_updated: "2026-03-23T13:51:04.103Z"
+status: "Phase 06 shipped — PR #145"
+stopped_at: "Completed 06-04 Task 1; checkpoint:human-verify at Task 2"
+last_updated: "2026-04-01T10:06:39.889Z"
 progress:
-  total_phases: 10
-  completed_phases: 9
-  total_plans: 24
-  completed_plans: 24
+  total_phases: 14
+  completed_phases: 12
+  total_plans: 31
+  completed_plans: 31
 ---
 
 # Project State
@@ -19,11 +19,11 @@ progress:
 See: .planning/PROJECT.md (updated 2026-03-17)
 
 **Core value:** Java developers can integrate Chroma quickly and safely with a predictable, strongly-typed client that behaves consistently across environments.
-**Current focus:** Phase 05 — cloud-integration-testing
+**Current focus:** Phase 06 — documentation-site
 
 ## Current Position
 
-Phase: 05
+Phase: 07
 Plan: Not started
 
 ## Performance Metrics
@@ -70,6 +70,10 @@ Plan: Not started
 | Phase 03-search-api P03 | 90 | 2 tasks | 7 files |
 | Phase 05-cloud-integration-testing P02 | 4 | 2 tasks | 1 files |
 | Phase 05 P03 | 5 | 1 tasks | 1 files |
+| Phase 06-documentation-site P01 | 3 | 2 tasks | 24 files |
+| Phase 06-documentation-site P03 | 7 | 2 tasks | 11 files |
+| Phase 06-documentation-site P02 | 4 | 2 tasks | 12 files |
+| Phase 06-documentation-site P04 | 5 | 1 tasks | 9 files |
 
 ## Accumulated Context
 
@@ -142,6 +146,15 @@ Recent decisions affecting current work:
 - [Phase 05-cloud-integration-testing]: CLOUD-01 search parity tests: GroupBy results via rows() only; ReadLevel WAL uses isolated collection without polling; RRF auto-skipped with Assume.assumeTrue false documenting server limitation; filter matrix 8 sub-scenarios inline; pagination client validation throws IllegalArgumentException before HTTP
 - [Phase 05-cloud-integration-testing]: Embedding projection assertion loosened to accept null or [[null]]: server returns [[null]] for unselected embeddings
 - [Phase 05-cloud-integration-testing]: WAL read-level test uses isolated 3D collection (col) instead of 4D seedCollection to avoid dimension mismatch
+- [Phase 06-documentation-site]: java-examples/index.md placed inside docs_dir (docs/docs/java-examples/) — MkDocs only serves content from docs_dir; placing outside caused strict-mode build failure
+- [Phase 06-documentation-site]: api/ nav entry uses api/index.md placeholder so mkdocs build --strict passes; actual Javadoc deployed by CI into api/ path over this placeholder
+- [Phase 06-documentation-site]: maven-javadoc-plugin upgraded from 2.9.1 to 3.11.2 with doclint=none and source=8 for modern HTML5 Javadoc output and Java 8 compatibility
+- [Phase 06-documentation-site]: Migration page uses pymdownx.tabbed for v1/v2 side-by-side examples — v1 code is the designated exception per D-11; all other pages are v2-only
+- [Phase 06-documentation-site]: ChromaLoggers is package-private; logging docs expose only ChromaLogger interface and ChromaLogger.noop() as the public API surface
+- [Phase 06-documentation-site]: SearchExample uses Search.builder() + collection.search().searches(...) pattern to expose full Knn/Rrf/Search type hierarchy
+- [Phase 06-documentation-site]: All guide pages use --8<-- named section snippet inclusions (no inline copy-pasted code blocks) per D-09
+- [Phase 06-documentation-site]: Examples stubs use 'coming soon' admonition with link to relevant guide page — Phase 7 fills content without touching nav config
+- [Phase 06-documentation-site]: mkdocs.yml Examples nav uses section syntax with java-examples/index.md as section index per navigation.indexes feature
 
 ### Roadmap Evolution
 
@@ -159,6 +172,6 @@ None.
 
 ## Session Continuity
 
-Last session: 2026-03-23T13:27:48.062Z
-Stopped at: Completed 05-cloud-integration-testing-05-03-PLAN.md
+Last session: 2026-03-24T15:42:20.817Z
+Stopped at: Completed 06-04 Task 1; checkpoint:human-verify at Task 2
 Resume file: None