docs: add comprehensive getting started guide and restructure documentation#209
Merged
Conversation
- Documented core concepts, including lifecycle, DI, middleware, and source generation. - Added a complete tutorial for creating the first Lambda function using aws-lambda-host. - Provided step-by-step examples, complete code, and testing/deployment instructions.
- Added detailed guide on dependency injection with examples and best practices. - Documented lifecycle management including OnInit, Invocation, and OnShutdown handlers. - Created a comprehensive index for accessing all framework guides. - Included troubleshooting, anti-patterns, and advanced configuration examples.
- Added new navigation tab options: sticky, expand, path, prune, and indexes. - Integrated Table of Contents (toc) support with navigation. - Improved navigation top configuration for better user experience.
- Documented `MapHandler` method for type-safe handler registration with examples. - Explained the `[Event]` attribute for deserialization and type safety. - Provided examples for dependency injection, async handlers, and return types. - Covered best practices, troubleshooting, and source generation optimizations. - Included detailed patterns for CRUD, validation, and cancellation handling.
- Introduced a comprehensive guide on framework and application configuration. - Documented `LambdaHostOptions` for control over lifecycle, timeouts, and serialization. - Explained application configuration patterns with `appsettings.json` and environment variables. - Added examples of strongly-typed options, validation, and environment-specific settings. - Covered JSON serialization, secrets management, and best practices for `IOptions<T>`. - Included troubleshooting tips for common configuration issues.
- Updated light and dark mode palettes with orange primary and accent colors. - Added a new "Guides" section with links to various framework documentation topics. - Removed unused `toc.integrate` option from navigation. - Improved structure for better theme customization and navigation clarity.
- Changed primary color in dark mode to black in mkdocs.yml configuration. - Enabled usage of custom `extra.css` for additional styling. - Added orange theme color definitions for primary, light, and dark variants in `extra.css`.
- Introduced detailed documentation on error handling strategies in AWS Lambda functions. - Covered handler, middleware, and lifecycle error handling patterns with examples. - Documented cancellation token management, including `InvocationCancellationBuffer` configuration. - Explained retry strategies, application-level retries, and AWS-native retry behaviors. - Added best practices, anti-patterns, and troubleshooting guidance for error handling. - Included examples of structured error responses, exception transformation, and logging. - Detailed lifecycle error handling during OnInit and OnShutdown phases.
- Added new navigation options: tracking, toc.follow, and instant navigation support. - Integrated advanced search options: highlight, share, and suggest functionalities. - Removed unused `navigation.prune` for cleaner configuration. - Improved formatting and indentation for better readability.
- Reformatted line breaks in index.md for better readability and consistency. - Enhanced table structures for package and envelope documentation. - Updated navigation in mkdocs.yml to support sub-navigation for "Home" and added "Changelog". - Included changelog.md for tracking version history and release notes.
- Changed CleanupCode profile in FormattingTasks.yml to "Full Cleanup Custom". - Adjusted formatting in docs/index.md for consistent indentation and spacing.
- Updated `AwsLambda.Host.sln.DotSettings` with a new "Full Custom Cleanup" profile. - Reformatted indentation and spacing in `docs/index.md` for consistency.
- Corrected inconsistent indentation in docs/index.md for better readability and uniformity. - Simplified the AWS Lambda example in Program.cs for clarity and ease of understanding.
- Removed "async-first design" mention for concise framework description. - Updated section title to "Lifecycle Management" with corresponding icon change. - Minor adjustments to streamline content and improve clarity.
- Introduced a detailed deployment guide for AWS Lambda, covering SAM, CDK, and Terraform. - Added instructions for CI/CD integration using GitHub Actions with SAM and Native AOT workflows. - Documented best practices, troubleshooting, and monitoring strategies for Lambda deployment. - Created a placeholder for testing guide, with plans to cover unit, integration, and lifecycle testing. - Included references to existing test patterns, examples, and tools for ongoing development.
- Deleted deprecated 'MANDATORY WORKFLOW' section from CLAUDE.md. - Removed obsolete C# 14 extension member syntax guide for clarity. - Retained relevant modern syntax instructions for extension members.
- Introduced a dedicated "Features" section to showcase framework extensions and capabilities. - Added extensive documentation for envelopes, covering supported event sources like SQS, SNS, Kinesis, and more. - Included an in-depth guide for OpenTelemetry integration, with examples for tracing and metrics setup. - Updated mkdocs.yml to include navigation for envelopes, OpenTelemetry, and custom serialization. - Enhanced navigation for quick access to envelope patterns, observability, and related guides.
- Removed `docs/features/envelopes/sqs.md` as part of restructuring envelope content. - Consolidated envelope documentation into `docs/features/envelopes/index.md` for a centralized overview. - Enhanced `index.md` with details on supported event sources, benefits, and configuration methods. - Updated examples to showcase the generic envelope pattern instead of SQS-specific content.
- Merged envelope sub-sections into a single `features/envelopes.md` for improved organization. - Removed individual entries for SQS, SNS, and other envelope types from `mkdocs.yml`. - Updated documentation structure to streamline navigation and simplify content discovery.
- Simplified `docs/features/index.md` by condensing envelope and observability sections. - Removed redundant examples and details, centralizing key information for clarity. - Updated links to reference consolidated envelope and observability documentation.
- Improved structure and organization of the OpenTelemetry documentation. - Clarified lifecycle integration with detailed examples for `OnInit`, `Invocation`, and `OnShutdown`. - Added sections on custom instrumentation for spans and metrics. - Expanded configuration examples for OTLP, X-Ray, and Prometheus exporters. - Included a practical guide for viewing traces with Jaeger and Lambda Test Tool.
…tailed setup - Updated OpenTelemetry integration documentation to include enhanced lifecycle examples. - Added explanations about compile-time instrumentation and shutdown trace flushing. - Expanded configuration sections for OTLP, X-Ray, and custom instrumentation. - Improved example code for better readability and alignment with best practices. - Included guidance for viewing traces using Jaeger and basic CURL commands.
…updated examples - Added detailed installation instructions for required packages, including OTLP and X-Ray exporters. - Updated example code to include `CancellationToken` for better asynchronous handling. - Reorganized content to enhance readability and follow a logical progression.
…dditional tips - Added inline comments in the code examples for better understanding of tracing configurations. - Included a section summarizing key setup steps with numbered annotations. - Updated mkdocs.yml to include the new `content.code.annotate` plugin for improved documentation.
…tails and package corrections - Added explanation of source generation and interceptors for performance optimization. - Replaced outdated `OpenTelemetry.Exporter.Otlp` package with `OpenTelemetry.Exporter.OpenTelemetryProtocol`. - Enhanced clarity in the "How It Works" section, focusing on optimized instrumentation flow. - Simplified configuration examples by removing excessive code while maintaining key details. - Updated `mkdocs.yml` to include `def_list` and `pymdownx.tasklist` Markdown extensions.
… instrumentation - Added sections on custom metrics instrumentation with `Counter` and `Metric` examples. - Expanded documentation to include handler and service instrumentation with detailed code samples. - Reorganized headings for improved readability and logical flow. - Included references to working example project for better hands-on understanding.
… and shutdown tips - Added notes about `TracerProvider` requirements in the DI container for proper functionality. - Included warnings and tips on trace flushing during application shutdown. - Enhanced documentation with Lambda execution environment lifecycle insights. - Fixed typos and improved readability in affected sections.
… for Lambda - Documented new helper methods: `OnShutdownFlushOpenTelemetry`, `OnShutdownFlushTracer`, and `OnShutdownFlushMeter`. - Added detailed descriptions of usage scenarios and parameters, including `timeoutMilliseconds`. - Clarified behavior of `TracerProvider` and `MeterProvider` during shutdown in serverless environments. - Enhanced warnings about Lambda lifecycle constraints during shutdown. - Fixed minor typos and improved Markdown formatting.
- Deleted `Deployment` section from `index.md` to streamline documentation. - Updated `mkdocs.yml` to reflect removal of deployment guide. - Added a new `Examples
… section - Created `Advanced Topics` with placeholders for Native AOT, performance tuning, and source generators. - Enhanced `Examples` section with notes on runnable Lambda applications and middleware usage. - Updated `Guides` formatting by adding spacing for improved readability. - Refined guide links in `Additional Resources` to reflect upcoming content and placeholders.
- Replaced lengthy sections with a concise explanation of DI concepts in Lambda functions. - Simplified `Service Lifetimes` and removed redundant examples for better focus. - Improved formatting and added practical usage tips for scoped, singleton, and transient services. - Enhanced `OnInit` and `OnShutdown` sections with streamlined examples and guidance. - Updated DI container creation example to prioritize core concepts and improved readability.
- Removed redundant and overly detailed examples for concise documentation. - Replaced repetitive setup instructions with clear pipeline execution basics. - Enhanced clarity of `ILambdaHostContext` usage and feature access explanations. - Introduced simplified tables and sections for improved readability and structure. - Updated middleware examples to use consistent logging with reduced verbosity.
…and improved examples - Added explanation of lazy feature creation using `IFeatureProvider` in `ILambdaHostContext.Features`. - Updated middleware example to demonstrate `CorrelationFeatureProvider` usage for added clarity. - Simplified steps for adding custom features and registering providers to reduce verbosity. - Improved formatting and example code consistency for better readability.
- Condensed sections on `OnInit`, `Invocation`, and `OnShutdown` phases for better readability. - Removed redundant examples and replaced them with concise, practical usage scenarios. - Enhanced lifecycle handler documentation with clear guidelines on best practices and DI usage. - Added structured logging examples and clarified `ClearLambdaOutputFormatting` benefits. - Improved formatting and example consistency across lifecycle phases for easier understanding.
- Deleted temporary resources section with outdated links and references in testing guide. - Removed unstructured testing examples and placeholder content for future updates. - Streamlined the guide format by focusing on relevant and practical testing topics.
- Condensed sections on handler mapping and `[Event]` attribute usage for better clarity. - Replaced redundant examples with concise, practical use cases. - Updated DI usage examples with relevant scenarios for services and keyed resolution. - Improved documentation structure with streamlined sections on serialization and lifecycle support. - Enhanced examples with logging, cancellation tokens, and best practices for better readability.
…amples - Added comprehensive code samples for `Program.cs` and `Handlers.cs` to clarify `MapHandler` usage. - Included DI and `CancellationToken` handling best practices in `Handlers.HandleAsync` example. - Improved guide structure with formatted examples for easier understanding and direct application.
…d feature examples - Updated middleware composition tips to promote decoupling and reduced DI complexity. - Enhanced `Features` section with examples of ASP.NET-style typed capabilities. - Improved guidance on using `IFeatureProvider` including registration and lazy creation patterns. - Expanded example code to illustrate coherent provider usage and maintainability best practices.
- Added spacing to improve readability in the Topics section. - Updated `Additional Resources` links with "Coming Soon" notes for clarity on upcoming content. - Enhanced descriptions for `Examples` and `Advanced Topics` with detailed placeholders. - Improved formatting consistency across the `index.md` guide.
- Fixed typo in the mention of "source generator internals" for consistency and clarity.
- Replaced future timestamps with realistic past dates in response examples for clarity. - Ensured consistency across similar example JSON structures in the guide.
- Condensed lifecycle phase explanations for improved clarity and focus. - Simplified examples for `OnInit`, `Invocation`, and `OnShutdown` phases with practical scenarios. - Updated diagrams and flowcharts for consistency with the new lifecycle structure. - Enhanced dependency injection section with a lifetime comparison table and concise explanations. - Improved middleware and feature usage examples with structured logging and reduced redundancy.
…t practices - Improved `LambdaHostOptions` section with detailed examples and updated table formats. - Added JSON and Bash code blocks to illustrate both file-based and environment variable configurations. - Enhanced examples for `ShutdownDuration`, `ClearLambdaOutputFormatting`, and custom serializer options. - Condensed `Options Pattern` section with clear guidance on environment-specific settings and validation. - Updated
- Replaced all mentions of `aws-lambda-host` with `AwsLambda.Host` across documentation for consistency. - Updated examples, headings, and explanations to align with the standardized naming convention. - Improved clarity by ensuring formatting consistency in code snippets, tables, and lists. - Enhanced readability in `Error Handling`, `Getting Started`, and `Core Concepts` guides.
- Introduced `hosting.md` to provide an in-depth guide on hosting and application building in Lambda. - Explained default behavior of `LambdaApplication.CreateBuilder()` with detailed feature breakdown. - Added examples for builder customization using `LambdaApplicationOptions` and service registration. - Documented runtime execution flow, middleware usage, lifecycle hooks, and troubleshooting tips. - Provided testing scenarios and alternate hosting approaches for enhanced application flexibility.
…d clarity - Updated `Envelopes` docs with revised definitions and streamlined explanations for key concepts. - Improved table formats for supported event sources and envelope packages. - Added comprehensive examples for `SqsEnvelope<T>` and custom envelope implementations. - Enhanced sections on `EnvelopeOptions` and global serialization configuration. - Introduced best practices for deserialization, error handling, and Native AOT support.
- Updated `index.md` with a clearer description of `AwsLambda.Host`, replacing outdated definitions. - Introduced new content under `Hosting & Builder` to guide advanced customization and troubleshooting. - Improved clarity and formatting in the `Examples` section, marking incomplete areas as "Coming Soon." - Streamlined `Why AwsLambda.Host` and feature highlights with refined language for better readability. - Enhanced table of contents in `mkdocs.yml` with the addition of `Hosting & Builder` and font updates. - Added `JetBrains Mono` font for improved readability of code snippets. - Enabled plugin for optimization while suppressing unnecessary print summaries.
- Consolidated event handling and observability sections under "Extend the Framework." - Updated links and descriptions for envelopes and OpenTelemetry integration. - Improved clarity and focus by removing redundant subsections for performance optimization. - Adjusted .gitignore to include a new `.cache/` entry.
- Replaced absolute paths with relative links across all documentation files. - Updated references in `getting-started`, `guides`, and `features` sections for improved portability. - Removed outdated sections such as `Troubleshooting` and `FAQ` to streamline documentation. - Enhanced link consistency in package tables and examples for improved navigation. - Fixed broken URLs and updated links to GitHub examples for clarity.
- Added a direct link to the full documentation in all package and example README files. - Enhanced navigation and accessibility for users to access detailed guides and resources.
…atting - Updated all README files to use consistent `[View Full Documentation]` link formatting. - Replaced the outdated inline text links with a standardized clickable markdown format. - Enhanced readability and navigation for users across all documentation.
- Standardized placement of `[View Full Documentation]` links across all README files. - Enhanced readability by moving duplicate links to a more prominent and consistent position. - Improved navigation for users accessing detailed documentation resources.
- Included installation of pngquant in the GitHub Actions workflow for image optimization. - Ensures compatibility with tools requiring pngquant during documentation build processes.
|
Codecov Report✅ All modified and coverable lines are covered by tests. @@ Coverage Diff @@
## main #209 +/- ##
=======================================
Coverage 90.92% 90.92%
=======================================
Files 102 102
Lines 2227 2227
Branches 252 252
=======================================
Hits 2025 2025
Misses 109 109
Partials 93 93 Continue to review full report in Codecov by Sentry.
🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🚀 Pull Request
📋 Summary
This PR adds a comprehensive getting started guide and completely restructures the project documentation. The new documentation includes:
The documentation now follows a clear learning path from installation through advanced topics, making it easier for developers to adopt the framework.
✅ Checklist
🧪 Related Issues or PRs
Part of the documentation improvement initiative.
💬 Notes for Reviewers
This is a substantial documentation overhaul with 60+ commits. Key areas to review:
The documentation site is built with MkDocs Material and includes:
Future work: