mirror of
https://github.com/mattermost/mattermost.git
synced 2026-08-01 09:08:03 -05:00
Eva SarafianouandCursor
5fbb2a32d6
* docs: vendor and stage Mattermost Agents docs for Docusaurus build The migration plan externalized Agents links, but the Docusaurus sidebar generator already declares an `agents` TOP_LEVEL category and stub pages link to `/agents/docs/*` paths with no content behind them. Vendor the mattermost-plugin-agents docs/ folder as a submodule and stage it into main/agents/docs/ at build time (mirroring how Sphinx handles the same submodule via conf.py excludes), so the Agents sidebar category and internal links resolve to real, versioned content instead of dead ends. Co-authored-by: Cursor <cursoragent@cursor.com> * docs: strip leading license comment before MDX-staging Agents docs Three feature pages (channel_summaries.md, custom_prompts.md, managing_agents.md) lead with a raw <!-- Copyright ... --> HTML comment before the # Title line, which broke both title extraction (regex only matched a title at the very start of the file) and the Docusaurus build (MDX doesn't parse bare HTML comments the way Markdown does, so it failed to compile with "Unexpected character '!'"). Strip the license comment before further processing instead of trying to convert it. Co-authored-by: Cursor <cursoragent@cursor.com> * docs: fail loudly on missing Agents submodule, fix usage comment path - A missing/uninitialized vendor/mattermost-plugin-agents submodule previously logged a warning and returned a successful zero-count result, letting CI/prestart/prebuild continue with an empty (or, on a reused workspace, stale) Agents section instead of failing. Now it clears any previously staged output first, then throws so the build fails clearly when the submodule isn't present. - Fixed the usage comment referencing the nonexistent docs-site/scripts path instead of the actual docs/site/scripts. Co-authored-by: Cursor <cursoragent@cursor.com> * docs: checkout submodules in docs-ci.yaml build check This is the third docs-building workflow (alongside docs-cd.yml and docs-preview-template.yml) that runs npm run build on docs/site, and it was missed when submodules: true was added to the other two — its "Build docs site" step failed on this PR because vendor/mattermost-plugin-agents wasn't checked out, which stage-agents-docs.mjs now correctly treats as a hard failure. Co-authored-by: Cursor <cursoragent@cursor.com> * docs: inline Agents content instead of a separate top-level LHS section Sphinx never gives Agents its own top-level nav entry: it `.. include::`s admin_guide.md/user_guide.md directly into the existing curated pages (administration-guide/configure/agents-admin-guide.rst and end-user-guide/agents.rst), and only nests a handful of files (providers, aws_bedrock_setup, sovereign_ai, usage_tips) as small hidden- toctree children of those same two pages. load-testing.md, upgrading_to_2.0.md, and all of features/*.md are never referenced in any Sphinx toctree at all. The previous vendoring approach staged all 12 files as a brand-new, disconnected top-level "Agents" category, so reaching the actual guide meant leaving the curated page, opening an unrelated top-level section, and drilling into "Docs" — the opposite of what Sphinx does today. This reproduces Sphinx's structure instead: - stage-agents-docs.mjs now categorizes the 12 vendored files: admin_guide/ user_guide are staged twice — once as a normal (but `unlisted: true`) doc for direct-link parity with Sphinx's orphan pages, and once as a Docusaurus Markdown partial (leading underscore, auto-excluded from routing/sidebars) for inline import. providers/aws_bedrock_setup/ sovereign_ai/usage_tips are staged as normal listed docs. Everything else is staged unlisted, matching Sphinx never surfacing them in nav. - Added generic relative-markdown-link rewriting (mirroring the existing image-path rewriting) so cross-links between vendored files (`../admin_guide.md#anchor`, `features/channel_summaries.md`, etc.) resolve correctly regardless of nesting depth or where the linking content ends up rendered. - agents-admin-guide.mdx and end-user-guide/agents.mdx now `import` and render the partials inline instead of linking out, and no longer link to a separate "Docs" section. - gen-documentation-sidebar.mjs: removed the standalone `agents` TOP_LEVEL category. Added `{doc: '<full id>'}` support to buildAdminConfigureItem for cross-directory group items, and a new ADMIN_CONFIGURE_GROUPS.agents group nesting providers/aws_bedrock_setup/ sovereign_ai under agents-admin-guide. Added a standalone promoteDocToCategory helper (End User Guide has no full manual-grouping override) to nest usage_tips under end-user-guide/agents. - Documented both patterns (cross-directory group items, Markdown-partial inlining) in docs/site/README.md's "Manual grouping overrides" section. Validated: stage-agents-docs.mjs + gen-documentation-sidebar.mjs both run clean with zero warnings; a scoped @mdx-js/mdx compile check across all 16 affected files (2 curated pages + 12 staged docs + 2 partials) passes with zero failures. Full `docusaurus build` still needs the OpenAPI prebuild's Go toolchain, unavailable in this sandbox — already covered by docs-ci.yaml in CI. Co-authored-by: Cursor <cursoragent@cursor.com> * docs(agents): self-host the plugin-v2 upgrade guide link Now that mattermost-plugin-agents/docs is vendored and staged into /agents/docs/*, point the two "how to upgrade to Agents v2" references (v11 changelog, important upgrade notes) at our own /agents/docs/upgrading_to_2.0 page instead of an external GitHub blob link — the same self-hosting fix already applied to the old dangling sample-file links. Co-authored-by: Cursor <cursoragent@cursor.com> * docs(agents): tighten stage-agents-docs.mjs header comment Same explanation, fewer words — trims the file-level comment from ~45 to ~33 lines without dropping the rationale (why staging instead of a direct submodule checkout, and how the three-way listed/unlisted/ inline-partial split reproduces Sphinx's nav). Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>
5 lines
179 B
Plaintext
5 lines
179 B
Plaintext
[submodule "docs/vendor/mattermost-plugin-agents"]
|
|
path = docs/vendor/mattermost-plugin-agents
|
|
url = https://github.com/mattermost/mattermost-plugin-agents.git
|
|
branch = master
|