feat: #3626343 Add MkDocs support and a site-builder-friendly documentation site

Jibran Ijazrequested to merge
issue/ai_agents_views-3626343:3626343-mkdocs-site-setup into 1.0.x

Summary

ai and ai_agents both publish a MkDocs site; ai_agents_views had neither a mkdocs.yml nor the pages CI stage those two rely on, so nothing in docs/ was ever built or published anywhere. Adds that support, reorganizes docs/ with the actual reader in mind (site builders using the module vs. contributors to it), and fixes two broken internal cross-references along the way - one a dead link outside docs_dir, the other a relative path that escaped the module root entirely instead of reaching its own sibling file.

Changes

  • mkdocs.yml (new): modeled on ai_agents's simpler configuration. Nav: Home, Example Prompts (Views Agent / Views Assistant), Views Assistant Submodule, Testing. architecture.md is intentionally left out of the nav - a repo-only contributor reference, not published to the site-builder-facing site.
  • docs/index.md (new): a site-builder-friendly Home page for the published site.
  • .gitlab-ci.yml: added the pages: stage: .post stub present in both sibling modules, required for the shared CI template to build/publish the site at all.
  • .gitignore (new): ignores /site, the MkDocs build output.
  • .cspell-project-words.txt: added mkdocs.
  • docs/prompts.md: replaced a dead link to ../config/install/ai_agents.ai_agent.views_agent.yml (outside docs_dir, unresolvable once published) with plain prose.
  • docs/views-assistant-prompts.md: fixed a broken relative link (../../docs/prompts.md, which escapes the module root rather than reaching its sibling file) to a real link, and reworded a claim that prior bug write-ups live "at the repo root" - they live in a different, outer project, not in this repository.
  • README.md: added a Documentation section (published-site link plus local mkdocs serve steps), converted bare doc-path mentions into real links, and added the docs/views-assistant-prompts.md reference that was missing entirely.

Test plan

  • mkdocs build --strict (mkdocs + mkdocs-material, in a throwaway virtualenv) against the module's mkdocs.yml builds cleanly (exit 0), with the only message being the expected, intentional notice that architecture.md exists but isn't in the nav.
  • Confirmed the two previously-broken cross-references now resolve: docs/views-assistant-prompts.md's link to prompts.md and every other internal doc link.
  • Not applicable: documentation and build-tooling change only, no code or config behavior to regression-test with PHPUnit.

Closes #3626343

AI-Generated: Yes (Used Claude Code to design the MkDocs setup, reorganize and fix the documentation, and verify the build.)

Merge request reports