add reporting guide

docs/guides/commands.md

@@ -21,3 +21,4 @@ The following commands are available (invoked as PR comments):
 - `@coderabbitai configuration` to show the current CodeRabbit configuration for
   the repository.
 - `@coderabbitai help` to get help.
+- `@coderabbitai generate docstrings` to generate docstrings for functions in the PR. Learn more about [docstrings generation](/finishing-touches/docstrings).

docs/guides/custom-reports.md

@@ -0,0 +1,362 @@
+---
+title: Custom Reports
+sidebar_label: Custom Reports
+description: Learn how to create custom reports with CodeRabbit Pro's flexible reporting system
+sidebar_position: 7
+---
+
+```mdx-code-block
+import ProPlanNotice from '@site/src/components/ProPlanNotice.mdx';
+
+<ProPlanNotice />
+```
+
+CodeRabbit Pro allows you to create custom reports tailored to your specific needs using a flexible prompt-based system. This guide will help you understand how to create effective custom reports.
+
+## Understanding Custom Reports
+
+Custom reports allow you to:
+
+- Define exactly what information you want to see
+- Specify the format and structure of the report
+- Set custom filtering and grouping rules
+- Generate reports in different languages
+
+## Creating Custom Report Templates
+
+### Basic Structure
+
+A custom report template consists of instructions that tell CodeRabbit what information to include and how to present it. Here's a basic example:
+
+```text
+Please provide a summary of:
+- All merged pull requests
+- Critical bug fixes
+- Code review discussions
+
+Group by:
+- Repository
+- Team
+
+Format using:
+- Bullet points for changes
+- Tables for statistics
+```
+
+### Example for different languages
+
+Japanese:
+
+```text
+レポートを英語ではなく日本語で送信してください。
+
+以下の要約を提供してください：
+- すべてのプルリクエスト活動
+- コードレビューの議論
+```
+
+French:
+
+```text
+Veuillez envoyer le rapport en français et non en anglais.
+
+Veuillez fournir un résumé de :
+- Toutes les activités de demandes de fusion
+- Discussions sur la révision de code
+```
+
+### Available Data Points
+
+Your custom reports can access the following PR information that you can reference in your prompts:
+
+#### Pull Request Status
+
+- `Merged`: boolean (true/false) - Whether the PR has been merged
+- `Draft`: boolean (true/false) - Whether the PR is in draft state
+- `State`: string ("open"/"closed") - Current state of the PR
+- `Mergeable`: boolean (true/false) - Whether the PR can be merged
+- `Is stale`: boolean - Whether PR has been inactive for over 168 hours
+
+#### Basic Information
+
+- `Pull request number`: number - The PR's identifier
+- `Title`: string - PR title
+- `URL`: string - Link to the PR
+- `Author name`: string - PR creator's username
+- `Created at`: datetime - When the PR was created
+- `Last activity`: datetime - Most recent activity timestamp
+- `Closed at`: datetime (if applicable) - When the PR was closed
+
+#### Additional Context
+
+- `Labels`: array of strings - All labels applied to the PR
+- `Reviewers`: array of strings - Assigned reviewers' usernames
+- `Description`: markdown - Full PR description
+- `Summary`: string - AI-generated summary of changes
+- `Comments`: array of objects
+  - `username`: string - Comment author
+  - `body`: markdown - Comment content
+
+Here's an example prompt that uses these data points:
+
+```text
+Generate a summary with the following format for each PR:
+
+## [PR Title](URL)
+**Status**: {Use these symbols based on state}
+- 🔀 if Merged is true
+- 📝 if Draft is true
+- 💬 if State is "open"
+- 🔒 if State is "closed" and not merged
+Add ⚠️ if Is stale is true
+
+**Author**: {Author name}
+**Created**: {Created at}
+**Labels**: {Labels joined by commas}
+**Reviewers**: {Reviewers joined by commas}
+
+### Summary
+{Summary limited to 50 words}
+
+### Recent Activity
+{List last 3 comments with username and content}
+```
+
+### Formatting Options
+
+CodeRabbit supports markdown formatting in custom reports. You can use:
+
+- Headers (`#`, `##`, `###`)
+- Lists (bullet points and numbered)
+- Tables
+- Code blocks
+- Bold and italic text
+- Links
+
+### Language Support
+
+You can generate reports in multiple languages by specifying the ISO language code in your template. For example:
+
+```text
+Language: fr
+Please provide a summary of:
+- All pull request activities
+- Code review discussions
+```
+
+## Advanced Features
+
+### Filtering
+
+Include specific filtering instructions in your template:
+
+```text
+Include only:
+- PRs with "critical" or "bug" labels
+- Changes to production code
+- Reviews from senior developers
+
+Exclude:
+- Automated commits
+- Documentation changes
+- Dependencies updates
+```
+
+### Custom Grouping
+
+Organize information using custom grouping rules:
+
+```text
+Group by:
+1. Priority (High/Medium/Low)
+2. Component (Frontend/Backend/Infrastructure)
+3. Team (Team A/Team B)
+
+Within each group, sort by:
+- Activity date (newest first)
+- Impact level
+```
+
+### Time-Based Analysis
+
+Add temporal analysis to your reports:
+
+```text
+Provide:
+- Week-over-week comparison
+- Trend analysis for the past month
+- Velocity metrics
+- Time to merge statistics
+```
+
+## Best Practices
+
+1. **Be Specific**
+
+   - Clearly define what should be included/excluded
+   - Use precise language to avoid ambiguity
+   - Specify exact metrics you want to track
+
+2. **Structure Matters**
+
+   - Start with high-level summaries
+   - Use consistent grouping patterns
+   - Include clear section breaks
+
+3. **Keep it Relevant**
+
+   - Focus on actionable information
+   - Avoid redundant data points
+   - Consider your audience's needs
+
+4. **Optimize Readability**
+   - Use appropriate formatting
+   - Include visual breaks
+   - Maintain consistent styling
+
+## Example Templates
+
+### Executive Summary Template
+
+```text
+Provide a high-level overview:
+1. Key metrics:
+   - Total PRs merged
+   - Average review time
+   - Code quality scores
+2. Notable achievements
+3. Blocking issues
+4. Resource allocation
+
+Format:
+- Use tables for metrics
+- Bullet points for achievements
+- Clear headers for sections
+```
+
+### Technical Deep Dive Template
+
+```text
+Generate a detailed technical report:
+1. Code changes:
+   - Architecture updates
+   - API modifications
+   - Database changes
+2. Testing coverage
+3. Performance impacts
+4. Security considerations
+
+Include:
+- Links to significant PRs
+- Code snippets for major changes
+- Technical debt analysis
+```
+
+### Advanced Formatting
+
+Heres a more advanced example of a custom report template:
+
+```text
+Generate a report of all pull requests in the following format:
+
+- As the first paragraph, start with "🟣" if merged, "⚫" if draft, "🟢" if open, "🔴" if closed
+  - On the same line, add the PR title in bold (and only the title; don't put anything else in bold after that)
+  - On the same line, add the PR browser link (do not use an api link)
+  - On the same line, add the last activity date in the format "Day Month Year, Hour:Minute AM/PM (Timezone)" in italic (don't put anything else in italic after that and make sure it's not bold)
+- Make a new bullet-point list of high-level changes in the PR
+  - Start each change with a gitmoji followed by a very terse one-liner to mention at a high level what the change does and to what part of the application it applies to
+  - Do not start with verbose non-speak such as "The pull request enhances" or "This PR introduces". Keep it terse and straight to the point. Start change descriptions with a verb
+  - Do not end with justifications or reasons for the changes such as "... enhancing type safety". Stick to the facts, do not make up the outcome of a change
+  - Limit to the 4 most relevant changes
+  - Examples: "✨ Add a rotating tagline on the home page", "🔧 Add func-style to ESLint", "📝 Add download badge to `README.md`", "✅ Add unit tests for comment trees", "👷 Create a pipeline to publish to npmjs.org", "🐛 Fix comment submission in posts", "📄 License under AGPL-3.0-or-later", "📱 Change post view for mobile", "💄 Make sidebar links blue", "🩹 Fix unfollow button", "🔒️ Limit login cookies to a specific subdomain", "🥅 Handle errors when commenting in a post", "🙈 Stop ignoring `.env` and start ignoring `.env.local` and `.env.*.local`", "⬆️ Update lemmy-js-client to v0.19.4", "🏷️ Define interfaces for pull request events", "🔐 Add environment variables for Bitbucket Server", "🚚 Rename exported client instances in test files", "🏷️ Add type alias `EventKey` and its type guard `isEventKey`", "🏗️ Aggregate exports for pull request events in an index file"
+- Start the next paragraph with "Blockers:" in bold
+  - Summarize any issues preventing the PR from progressing
+    - Some examples: "Waiting for merge", "Waiting for review", "Failing CI/CD", "Needs more tests", "Needs rebase", "@username is waiting for a response", etc.
+  - If the PR is stale, note it here
+- Do not add a "Report" heading
+- Make sure there is one empty line between each paragraph
+
+These are the available emojis and the type of change they represent. Do not using any other emoji. Make sure the change corresponds to the gitmoji.
+
+<gitmojis>
+🎨: Improve structure / format of the code.
+⚡️: Improve performance.
+🔥: Remove code or files.
+🐛: Fix a bug.
+🚑️: Critical hotfix.
+✨: Introduce new features.
+📝: Add or update documentation.
+🚀: Deploy stuff.
+💄: Add or update the UI and style files.
+🎉: Begin a project.
+✅: Add, update, or pass tests.
+🔒️: Fix security or privacy issues.
+🔐: Add or update secrets.
+🔖: Release / Version tags.
+🚨: Fix compiler / linter warnings.
+🚧: Work in progress.
+💚: Fix CI Build.
+⬇️: Downgrade dependencies.
+⬆️: Upgrade dependencies.
+📌: Pin dependencies to specific versions.
+👷: Add or update CI build system.
+📈: Add or update analytics or track code.
+♻️: Refactor code.
+➕: Add a dependency.
+➖: Remove a dependency.
+🔧: Add or update configuration files.
+🔨: Add or update development scripts.
+🌐: Internationalization and localization.
+✏️: Fix typos.
+💩: Write bad code that needs to be improved.
+⏪️: Revert changes.
+🔀: Merge branches.
+📦️: Add or update compiled files or packages.
+👽️: Update code due to external API changes.
+🚚: Move or rename resources (e.g.: files, paths, routes).
+📄: Add or update license.
+💥: Introduce breaking changes.
+🍱: Add or update assets.
+♿️: Improve accessibility.
+💡: Add or update comments in source code.
+🍻: Write code drunkenly.
+💬: Add or update text and literals.
+🗃️: Perform database related changes.
+🔊: Add or update logs.
+🔇: Remove logs.
+👥: Add or update contributor(s).
+🚸: Improve user experience / usability.
+🏗️: Make architectural changes.
+📱: Work on responsive design.
+🤡: Mock things.
+🥚: Add or update an easter egg.
+🙈: Add or update a .gitignore file.
+📸: Add or update snapshots.
+⚗️: Perform experiments.
+🔍️: Improve SEO.
+🏷️: Add or update types.
+🌱: Add or update seed files.
+🚩: Add, update, or remove feature flags.
+🥅: Catch errors.
+💫: Add or update animations and transitions.
+🗑️: Deprecate code that needs to be cleaned up.
+🛂: Work on code related to authorization, roles and permissions.
+🩹: Simple fix for a non-critical issue.
+🧐: Data exploration/inspection.
+⚰️: Remove dead code.
+🧪: Add a failing test.
+👔: Add or update business logic.
+🩺: Add or update healthcheck.
+🧱: Infrastructure related changes.
+🧑‍💻: Improve developer experience.
+💸: Add sponsorships or money related infrastructure.
+🧵: Add or update code related to multithreading or concurrency.
+🦺: Add or update code related to validation.
+</gitmojis>
+```
+
+## Related Resources
+
+- [Scheduled Reports](./scheduled-reports.md)
+- [On-demand Reports](./ondemand-reports.md)
+- [API Documentation](https://api.coderabbit.ai/api/swagger/)

docs/guides/ondemand-reports.md

@@ -2,7 +2,7 @@
 title: On-demand Reports
 sidebar_label: On-demand Reports
 description: CodeRabbit offers a way to generate on-demand reports using a simple API request
-sidebar_position: 6
+sidebar_position: 8
 ---
 
 ```mdx-code-block
@@ -12,6 +12,18 @@ import ProPlanNotice from '@site/src/components/ProPlanNotice.mdx';
 <ProPlanNotice />
 ```
 
+## Overview
+
+CodeRabbit's reporting feature helps you track and analyze pull request activity across your repositories. There are two ways to generate reports:
+
+1. **[Scheduled Reports](./scheduled-reports.md)** - Set up automated recurring reports that are delivered on a schedule to your preferred channels (email, Slack, MS Teams). This is the recommended way to keep your team informed about development progress.
+
+2. **On-demand Reports** (this guide) - Generate reports programmatically through our API when you need them. This is useful for integration with your own tools and workflows.
+
+If you're new to CodeRabbit's reporting features, we recommend starting with [Scheduled Reports](./scheduled-reports.md) to understand the available options and capabilities.
+
+## API Access
+
 CodeRabbit offers a way to generate on-demand reports using the [CodeRabbit API](https://api.coderabbit.ai/api/swagger/).
 You will need an API Key to access the CodeRabbit API and generate an on-demand report.