feat: enhance documentation structure and generation for agents

[pmalarme]

This pull request introduces a new Sphinx-based documentation pipeline for the project, replacing the previous experimental py2docfx approach. It adds per-agent and unified documentation sites, updates dependencies and build scripts, and provides comprehensive guides for building and managing documentation. The changes also include new Sphinx configuration and source files for both the unified docs and agent1, as well as updates to documentation-related tasks in the build system.

Documentation Pipeline Overhaul

• Replaces the old py2docfx-based documentation generator with a new scripts/generate_docs.py that builds HTML documentation for each agent and for a unified site using Sphinx (autodoc + napoleon). The script supports per-agent and unified builds, agent filtering, and path overrides. [1] [2]
• Adds a new docs/manual/docs-build-guide.md with detailed instructions, best practices, and CI recommendations for building documentation.
• Updates the root pyproject.toml to use Sphinx and related extensions for the docs dependency group and re-enables the documentation tasks (docs, docs-install) in the task runner. [1] [2]

Sphinx Documentation Sources and Configuration

• Adds unified Sphinx documentation sources and configuration in docs/source/, including index.rst and conf.py, to generate a combined documentation site. [1] [2]
• Adds per-agent Sphinx documentation sources and configuration for agent1 in agents/agent1/docs/source/, including index.rst, agent1.rst, and conf.py. [1] [2] [3]

Build System and Task Updates

• Adds a per-agent documentation build task (docs) to agents/agent1/pyproject.toml for local docs generation, and updates documentation in the agent guide template to reference the new docs structure and build process. [1] [2]

These changes collectively standardize and streamline the documentation process for both individual agents and the overall project, making it easier to generate, maintain, and publish API documentation.

[Copilot]

Pull request overview

This pull request replaces the experimental py2docfx documentation pipeline with a production-ready Sphinx-based system. It introduces comprehensive documentation generation capabilities for both individual agents and a unified documentation site.

Changes:

• Replaces py2docfx with Sphinx (autodoc + napoleon) for HTML documentation generation
• Adds Sphinx configuration and source files for unified and per-agent documentation sites
• Updates dependencies, build tasks, and adds comprehensive documentation build guides

Reviewed changes

Copilot reviewed 11 out of 13 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
scripts/generate_docs.py	Complete rewrite to use Sphinx instead of py2docfx, with support for per-agent and unified builds
pyproject.toml	Updates docs dependency group from py2docfx to sphinx with extensions, re-enables docs tasks
docs/source/conf.py	New Sphinx configuration for unified documentation site
docs/source/index.rst	New root index for unified documentation
docs/source/agents/agent1/index.rst	New agent1 documentation page for unified site
agents/agent1/docs/source/conf.py	New Sphinx configuration for agent1 standalone docs
agents/agent1/docs/source/index.rst	New root index for agent1 standalone docs
agents/agent1/docs/source/agent1.rst	New agent1 module documentation page
agents/agent1/pyproject.toml	Adds docs task for per-agent documentation builds
docs/manual/docs-build-guide.md	New comprehensive guide for building documentation
docs/manual/agent-guide-template.md	Updates to reference new documentation structure
.gitignore	Adds patterns to ignore Sphinx autosummary cache directories

Comments suppressed due to low confidence (1)

docs/manual/agent-guide-template.md:81

• The original line "Project-level (root): shared tasks, root pyproject.toml, shared scripts (scripts/), CI, global lint/type/test settings." was removed but this information is still relevant and should be retained. Only the agent-level documentation was added as a new bullet point, but the project-level information should not have been deleted.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 13 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 14 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.