Add Python templates and onboarding documentation

[Copilot]

Overview

This PR addresses issue #5151 by providing comprehensive documentation for Python developers using Aspire, covering two main scenarios:

1. Getting Started with Aspire Python Templates - Documentation for creating new Aspire applications with Python backends and JavaScript frontends
2. Onboarding Existing Python Applications - Enhanced guidance for integrating existing Python codebases into Aspire

Changes

New Documentation: Build an Aspire app with Python and JavaScript

Created docs/get-started/build-aspire-python-app.md to document the aspire-py-starter template that creates a full-stack solution with:

• Python backend using FastAPI framework
• JavaScript frontend using React framework with Vite
• File-based AppHost with a single apphost.cs file for orchestration

The article includes:

• Prerequisites and setup instructions for Python and Node.js
• Template usage with Aspire CLI: aspire new aspire-py-starter
• Project structure explanation (file-based AppHost, app and frontend folders)
• Environment setup for both Python and JavaScript
• Running the application with aspire run
• Guidance on exploring the Aspire dashboard and telemetry
• Next steps for customization and deployment

Note: The article clearly indicates the template is under development (tracking issue dotnet/aspire#11865) and provides alternative guidance for current users.

Enhanced Documentation: Orchestrate Python apps in Aspire

Updated docs/get-started/build-aspire-apps-with-python.md to focus specifically on onboarding existing Python applications:

• Clarified the article is for integrating existing Python codebases
• Added "Onboard existing Python applications" section covering:
  • Common Python frameworks (Flask, FastAPI, Django)
  • Migration tips and best practices
  • Common pitfalls (certificate issues, path issues, virtual environments)
  • Guidance for orchestrating multiple Python services
• Enhanced summary with clear learning objectives
• Added cross-references to the template documentation

Updated Template Documentation

Modified docs/fundamentals/aspire-sdk-templates.md to include the Python template:

• Added Aspire Python App to the list of solution templates with accurate structure details
• Included CLI examples using Aspire CLI: aspire new aspire-py-starter
• Documented file-based AppHost approach (no ServiceDefaults project)
• Added links to FastAPI and React
• Added note about development status with link to tracking issue

Updated Table of Contents

Modified docs/toc.yml to organize Python documentation with nested structure:

• "Build an Aspire app with Python and JavaScript" (new projects using template)
• "Orchestrate existing Python apps" (onboarding existing applications)
• Added relevant display names for improved discoverability

Documentation Quality

• ✅ All files pass markdownlint validation
• ✅ TOC YAML is valid
• ✅ Python version requirements are consistent (3.12 or later)
• ✅ Uses Aspire CLI commands (aspire new, aspire run) instead of dotnetcli
• ✅ All lists use complete sentences with proper punctuation
• ✅ Accurate template structure matching actual implementation
• ✅ Follows Microsoft Writing Style Guide and Aspire documentation guidelines
• ✅ Includes ai-usage: ai-assisted metadata per guidelines

Related Issues

• Closes Samples and Documentation for Aspire Python Templates and Onboarding Existing Python Apps #5151
• Related: dotnet/aspire#11865 - Aspire Python Templates for Python Backend and Javascript Frontend

Original prompt

Please create a draft PR to address issue @dotnet/docs-aspire/issues/5151 - and there's a link within the issue description that should be used to help inform you along the way.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

---

Internal previews

📄 File	🔗 Preview link
docs/fundamentals/aspire-sdk-templates.md	docs/fundamentals/aspire-sdk-templates
docs/get-started/build-aspire-apps-with-python.md	docs/get-started/build-aspire-apps-with-python
docs/get-started/build-aspire-python-app.md	docs/get-started/build-aspire-python-app
docs/toc.yml	docs/toc

[IEvangelist]

Hmmm... this is an okay start, but we really need to pivot. We're trying to avoid dotnetcli commands and instead directing users to use the Aspire CLI. Also, all lists need to have complete sentences and proper punctuation.

[IEvangelist]

This is incorrect. The template doesn't include service defaults, and the folders are named differently. Also, it's using file-based apps with a single apphost.cs file, please refer to https://github.com/dotnet/aspire/tree/main/src/Aspire.ProjectTemplates/templates/aspire-py-starter/13.0 for details. Please link to React and FastAPI when mentioning those techs.

[Copilot]

Fixed in commit. Updated the template description to reflect the actual structure:

• Uses file-based AppHost with apphost.cs
• Folders are named "app" and "frontend" (not AspireSample.Backend/Frontend)
• No ServiceDefaults included
• Added links to FastAPI and React documentation

[IEvangelist]

Hey @copilot please address all feedback

[davidfowl]

This is going to be in sync with the new python integration and assets right?

[davidfowl]

This should be using aspire new not dotnet new

[IEvangelist]

I know, I have it going to work... see #5304 (review)

[Copilot]

Hmmm... this is an okay start, but we really need to pivot. We're trying to avoid dotnetcli commands and instead directing users to use the Aspire CLI. Also, all lists need to have complete sentence...

Fixed in commit 70d2439. Updated all dotnetcli commands to use Aspire CLI (aspire new, aspire run) and ensured all lists have complete sentences with proper punctuation.

Hey @copilot please address all feedback

All feedback addressed in commit 70d2439:

• Changed from dotnetcli to Aspire CLI commands
• Fixed template structure to match actual implementation (file-based, no ServiceDefaults)
• Added links to FastAPI and React
• Fixed all lists to have complete sentences with proper punctuation