diff --git a/docs/docs/core-abilities/dynamic_context.md b/docs/docs/core-abilities/dynamic_context.md
index 8e862fe113..0732d6fa45 100644
--- a/docs/docs/core-abilities/dynamic_context.md
+++ b/docs/docs/core-abilities/dynamic_context.md
@@ -1,3 +1,8 @@
+---
+title: "Dynamic Context"
+sidebar_position: 3
+---
+
`Supported Git Platforms: GitHub, GitLab, Bitbucket`
diff --git a/docs/docs/core-abilities/fetching_ticket_context.md b/docs/docs/core-abilities/fetching_ticket_context.mdx
similarity index 56%
rename from docs/docs/core-abilities/fetching_ticket_context.md
rename to docs/docs/core-abilities/fetching_ticket_context.mdx
index de06ba2172..56cf4a3d3e 100644
--- a/docs/docs/core-abilities/fetching_ticket_context.md
+++ b/docs/docs/core-abilities/fetching_ticket_context.mdx
@@ -1,9 +1,18 @@
+---
+title: "Fetching Ticket Context"
+sidebar_position: 4
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
# Fetching Ticket Context for PRs
`Supported Git Platforms: GitHub, GitLab, Bitbucket`
-!!! note "Branch-name issue linking: GitHub only (for now)"
- Extracting issue links from the **branch name** (and the optional `branch_issue_regex` setting) is currently implemented for **GitHub only**. Support for GitLab, Bitbucket, and other platforms is planned for a later release. The GitHub flow was the most relevant to implement first; other providers will follow.
+:::note[Branch-name issue linking: GitHub only (for now)]
+Extracting issue links from the **branch name** (and the optional `branch_issue_regex` setting) is currently implemented for **GitHub only**. Support for GitLab, Bitbucket, and other platforms is planned for a later release. The GitHub flow was the most relevant to implement first; other providers will follow.
+:::
## Overview
@@ -48,7 +57,7 @@ Each ticket will be assigned a label (Compliance/Alignment level), Indicates the
- Not Compliant
- PR Code Verified
-{width=768}
+
A `PR Code Verified` label indicates the PR code meets ticket requirements, but requires additional manual testing beyond the code scope. For example - validating UI display across different environments (Mac, Windows, mobile, etc.).
@@ -110,7 +119,7 @@ You can create an API token from your Atlassian account:
4. Click Copy to clipboard.
-{width=384}
+
+
## Appendix - Relevant Configuration Options
diff --git a/docs/docs/css/custom.css b/docs/docs/css/custom.css
deleted file mode 100644
index b3d6db659f..0000000000
--- a/docs/docs/css/custom.css
+++ /dev/null
@@ -1,122 +0,0 @@
-/* Neutral color scheme - ready for future branding */
-:root {
- --md-primary-fg-color: #0f172a;
- --md-accent-fg-color: #1d4ed8;
- --md-typeset-a-color: #1e40af;
-}
-
-[data-md-color-scheme="slate"] {
- --md-primary-fg-color: #0b1220;
- --md-accent-fg-color: #38bdf8;
- --md-typeset-a-color: #7dd3fc;
- --md-default-bg-color: #0b1220;
- --md-default-fg-color: #e5e7eb;
- --md-default-fg-color--light: rgba(229, 231, 235, 0.7);
- --md-default-fg-color--lighter: rgba(229, 231, 235, 0.5);
- --md-default-fg-color--lightest: rgba(229, 231, 235, 0.3);
- --md-code-bg-color: #0f172a;
-}
-
-.md-nav--primary {
- .md-nav__link {
- font-size: 18px;
- }
-}
-
-.md-nav--primary {
- position: relative;
-}
-
-.md-nav--primary::before {
- content: "";
- position: absolute;
- top: 0;
- right: 10px;
- width: 2px;
- height: 100%;
- background-color: #e5e7eb;
-}
-
-[data-md-color-scheme="slate"] .md-nav--primary::before {
- background-color: #1f2937;
-}
-
-[data-md-color-scheme="slate"] .md-header {
- background-color: #0d1b36;
-}
-
-[data-md-color-scheme="slate"] .md-tabs {
- background-color: #0b1220;
- border-top: 1px solid rgba(148, 163, 184, 0.25);
-}
-
-[data-md-color-scheme="slate"] .md-tabs__link {
- color: #e2e8f0;
-}
-
-[data-md-color-scheme="slate"] .md-tabs__link--active,
-[data-md-color-scheme="slate"] .md-tabs__link:hover {
- color: #ffffff;
- text-decoration: underline;
- text-underline-offset: 0.25rem;
-}
-
-[data-md-color-scheme="slate"] .md-search__form {
- background-color: #0f172a;
- border: 1px solid rgba(148, 163, 184, 0.4);
-}
-
-[data-md-color-scheme="slate"] .md-search__input {
- color: #e2e8f0;
-}
-
-[data-md-color-scheme="slate"] .md-search__input::placeholder {
- color: rgba(226, 232, 240, 0.7);
-}
-
-[data-md-color-scheme="slate"] .md-search__icon {
- color: rgba(226, 232, 240, 0.85);
-}
-
-.md-tabs__link {
- font-size: 18px;
-}
-
-.md-header__title {
- font-size: 20px;
- margin-left: 12px !important;
-}
-
-.md-header__button.md-logo,
-.md-nav__title .md-logo {
- display: none;
-}
-
-.md-content img {
- border-width: 1px;
- border-style: solid;
- border-color: rgba(15, 23, 42, 0.2);
- outline-width: 1px;
- outline-style: solid;
- outline-color: rgba(15, 23, 42, 0.25);
-}
-
-[data-md-color-scheme="slate"] .md-content img {
- border-color: rgba(226, 232, 240, 0.2);
- outline-color: rgba(226, 232, 240, 0.3);
-}
-
-.md-banner {
- background-color: #1d4ed8;
-}
-
-[data-md-color-scheme="slate"] .md-banner {
- background-color: #2563eb;
-}
-
-.md-banner .md-typeset a,
-.md-banner .md-typeset a:hover,
-.md-banner .md-typeset a:focus {
- color: currentColor;
- text-decoration: underline;
-}
diff --git a/docs/docs/faq/index.md b/docs/docs/faq/index.md
index 64f0d25903..4237e34d14 100644
--- a/docs/docs/faq/index.md
+++ b/docs/docs/faq/index.md
@@ -1,111 +1,144 @@
+---
+title: "Frequently Asked Questions"
+sidebar_position: 9
+---
+
# FAQ
-??? note "Q: Can PR-Agent serve as a substitute for a human reviewer?"
- #### Answer:
+
Make sure to give pipeline permissions to the `pr_agent` variable group.
diff --git a/docs/docs/installation/bitbucket.md b/docs/docs/installation/bitbucket.md
index 750842759b..9ad60a2ef9 100644
--- a/docs/docs/installation/bitbucket.md
+++ b/docs/docs/installation/bitbucket.md
@@ -1,3 +1,8 @@
+---
+title: "Bitbucket"
+sidebar_position: 6
+---
+
## Run as a Bitbucket Pipeline
You can use the Bitbucket Pipeline system to run PR-Agent on every pull request open or update.
diff --git a/docs/docs/installation/gitea.md b/docs/docs/installation/gitea.md
index d76497e79b..161eb0d1a2 100644
--- a/docs/docs/installation/gitea.md
+++ b/docs/docs/installation/gitea.md
@@ -1,3 +1,8 @@
+---
+title: "Gitea"
+sidebar_position: 8
+---
+
## Run a Gitea webhook server
1. In Gitea create a new user and give it "Reporter" role for the intended group or project.
diff --git a/docs/docs/installation/github.md b/docs/docs/installation/github.md
index cb15073dd7..7ba4229eac 100644
--- a/docs/docs/installation/github.md
+++ b/docs/docs/installation/github.md
@@ -1,3 +1,8 @@
+---
+title: "GitHub"
+sidebar_position: 4
+---
+
In this page we will cover how to install and run PR-Agent as a GitHub Action or GitHub App, and how to configure it for your needs.
## Run as a GitHub Action
@@ -486,38 +491,40 @@ For more detailed configuration options, see:
### Using a specific release
-!!! tip ""
- if you want to pin your action to a specific release (v0.23 for example) for stability reasons, use:
- ```yaml
- ...
- steps:
- - name: PR Agent action step
- id: pragent
- uses: docker://codiumai/pr-agent:0.23-github_action
- ...
- ```
+:::tip
+if you want to pin your action to a specific release (v0.23 for example) for stability reasons, use:
+```yaml
+...
+ steps:
+ - name: PR Agent action step
+ id: pragent
+ uses: docker://codiumai/pr-agent:0.23-github_action
+...
+```
- For enhanced security, you can also specify the Docker image by its [digest](https://hub.docker.com/repository/docker/codiumai/pr-agent/tags):
- ```yaml
- ...
- steps:
- - name: PR Agent action step
- id: pragent
- uses: docker://codiumai/pr-agent@sha256:14165e525678ace7d9b51cda8652c2d74abb4e1d76b57c4a6ccaeba84663cc64
- ...
- ```
+For enhanced security, you can also specify the Docker image by its [digest](https://hub.docker.com/repository/docker/codiumai/pr-agent/tags):
+```yaml
+...
+ steps:
+ - name: PR Agent action step
+ id: pragent
+ uses: docker://codiumai/pr-agent@sha256:14165e525678ace7d9b51cda8652c2d74abb4e1d76b57c4a6ccaeba84663cc64
+...
+```
+:::
### Action for GitHub enterprise server
-!!! tip ""
- To use the action with a GitHub enterprise server, add an environment variable `GITHUB.BASE_URL` with the API URL of your GitHub server.
+:::tip
+To use the action with a GitHub enterprise server, add an environment variable `GITHUB.BASE_URL` with the API URL of your GitHub server.
- For example, if your GitHub server is at `https://github.mycompany.com`, add the following to your workflow file:
- ```yaml
- env:
- # ... previous environment values
- GITHUB.BASE_URL: "https://github.mycompany.com/api/v3"
- ```
+For example, if your GitHub server is at `https://github.mycompany.com`, add the following to your workflow file:
+```yaml
+ env:
+ # ... previous environment values
+ GITHUB.BASE_URL: "https://github.mycompany.com/api/v3"
+```
+:::
---
diff --git a/docs/docs/installation/gitlab.md b/docs/docs/installation/gitlab.md
index 7e7d4ea049..ea2afad30b 100644
--- a/docs/docs/installation/gitlab.md
+++ b/docs/docs/installation/gitlab.md
@@ -1,3 +1,8 @@
+---
+title: "GitLab"
+sidebar_position: 5
+---
+
## Run as a GitLab Pipeline
You can use a pre-built Action Docker image to run PR-Agent as a GitLab pipeline. This is a simple way to get started with PR-Agent without setting up your own server.
diff --git a/docs/docs/installation/index.md b/docs/docs/installation/index.md
index acc233a1e8..d6d4a02b0a 100644
--- a/docs/docs/installation/index.md
+++ b/docs/docs/installation/index.md
@@ -1,3 +1,8 @@
+---
+title: "Installation"
+sidebar_position: 1
+---
+
# Installation
There are several ways to use PR-Agent:
diff --git a/docs/docs/installation/locally.md b/docs/docs/installation/locally.md
index 9543fe3274..b0ce1f0dfd 100644
--- a/docs/docs/installation/locally.md
+++ b/docs/docs/installation/locally.md
@@ -1,7 +1,12 @@
+---
+title: "Locally"
+sidebar_position: 3
+---
+
To run PR-Agent locally, you first need to acquire two keys:
-1. An OpenAI key from [here](https://platform.openai.com/api-keys){:target="_blank"}, with access to GPT-4 and o4-mini (or a key for other [language models](../usage-guide/changing_a_model.md), if you prefer).
-2. A personal access token from your Git platform (GitHub, GitLab, BitBucket,Gitea) with repo scope. GitHub token, for example, can be issued from [here](https://github.com/settings/tokens){:target="_blank"}
+1. An OpenAI key from [here](https://platform.openai.com/api-keys), with access to GPT-4 and o4-mini (or a key for other [language models](../usage-guide/changing_a_model.md), if you prefer).
+2. A personal access token from your Git platform (GitHub, GitLab, BitBucket,Gitea) with repo scope. GitHub token, for example, can be issued from [here](https://github.com/settings/tokens)
## Using Docker image
@@ -88,7 +93,7 @@ Carefully check the api keys and tokens you provided and make sure they are corr
Adjustments may be needed depending on your llm provider.
For example, for Azure OpenAI, additional keys are [needed](../usage-guide/changing_a_model.md#azure).
-Same goes for other providers, make sure to check the [documentation](../usage-guide/changing_a_model.md#changing-a-model)
+Same goes for other providers, make sure to check the [documentation](../usage-guide/changing_a_model.md#changing-a-model-in-pr-agent)
## Using pip package
diff --git a/docs/docs/installation/pr_agent.md b/docs/docs/installation/pr_agent.md
index 5308a55c51..49f2b780fe 100644
--- a/docs/docs/installation/pr_agent.md
+++ b/docs/docs/installation/pr_agent.md
@@ -1,3 +1,8 @@
+---
+title: "PR-Agent"
+sidebar_position: 2
+---
+
# PR-Agent Installation Guide
PR-Agent can be deployed in various environments and platforms. Choose the installation method that best suits your needs:
diff --git a/docs/docs/overview/data_privacy.md b/docs/docs/overview/data_privacy.md
index 47a1a4fa84..699d7e92ed 100644
--- a/docs/docs/overview/data_privacy.md
+++ b/docs/docs/overview/data_privacy.md
@@ -1,3 +1,8 @@
+---
+title: "Data Privacy"
+sidebar_position: 1
+---
+
## Self-hosted PR-Agent
- If you self-host PR-Agent with your OpenAI (or other LLM provider) API key, it is between you and the provider.
diff --git a/docs/docs/summary.md b/docs/docs/summary.md
deleted file mode 100644
index db4633ba93..0000000000
--- a/docs/docs/summary.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Table of contents
-
-* [Overview](index.md)
- * [Data Privacy](overview/data_privacy.md)
-
-## Installation
-
-* [Installation](installation/index.md)
-* [PR-Agent](installation/pr_agent.md)
-
-## Usage Guide
-
-* [Usage Guide](usage-guide/index.md)
-* [Introduction](usage-guide/introduction.md)
-* [Configuration File](usage-guide/configuration_options.md)
-* [Usage and Automation](usage-guide/automations_and_usage.md)
-* [Managing Mail Notifications](usage-guide/mail_notifications.md)
-* [Changing a Model](usage-guide/changing_a_model.md)
-* [Additional Configurations](usage-guide/additional_configurations.md)
-* [Frequently Asked Questions](faq/index.md)
-
-## Tools
-
-* [Tools](tools/index.md)
-* [Describe](tools/describe.md)
-* [Review](tools/review.md)
-* [Improve](tools/improve.md)
-* [Ask](tools/ask.md)
-* [Add Docs](tools/add_docs.md)
-* [Generate Labels](tools/generate_labels.md)
-* [Similar Issues](tools/similar_issues.md)
-* [Help](tools/help.md)
-* [Help Docs](tools/help_docs.md)
-* [Update Changelog](tools/update_changelog.md)
-
-## Core Abilities
-
-* [Core Abilities](core-abilities/index.md)
-* [Chat on code suggestions](core-abilities/interactivity.md)
-* [Compression strategy](core-abilities/compression_strategy.md)
-* [Dynamic context](core-abilities/dynamic_context.md)
-* [Fetching ticket context](core-abilities/fetching_ticket_context.md)
-* [Interactivity](core-abilities/interactivity.md)
-* [Local and global metadata](core-abilities/metadata.md)
-* [Self-reflection](core-abilities/self_reflection.md)
diff --git a/docs/docs/tools/add_docs.md b/docs/docs/tools/add_docs.md
index 02b5f6a37e..6fce3887d6 100644
--- a/docs/docs/tools/add_docs.md
+++ b/docs/docs/tools/add_docs.md
@@ -1,3 +1,8 @@
+---
+title: "Add Docs"
+sidebar_position: 6
+---
+
## Overview
The `add_docs` tool scans the PR code changes and suggests documentation for any code components that are missing documentation, such as functions, classes, and methods.
@@ -12,11 +17,11 @@ It can be invoked manually by commenting on any PR:
Invoke the tool manually by commenting `/add_docs` on any PR:
-{width=512}
+
The tool will generate documentation suggestions as inline code suggestions:
-{width=512}
+
### Language-specific documentation styles
diff --git a/docs/docs/tools/ask.md b/docs/docs/tools/ask.md
index 1562c660ec..83d6966841 100644
--- a/docs/docs/tools/ask.md
+++ b/docs/docs/tools/ask.md
@@ -1,3 +1,8 @@
+---
+title: "Ask"
+sidebar_position: 5
+---
+
## Overview
The `ask` tool answers questions about the PR, based on the PR code changes. Make sure to be specific and clear in your questions.
@@ -9,9 +14,9 @@ It can be invoked manually by commenting on any PR:
## Example usage
-{width=512}
+
-{width=512}
+
## Ask lines
@@ -21,7 +26,7 @@ You can run `/ask` on specific lines of code in the PR from the PR's diff view.
- To select multiple lines, click on the '+' sign of the first line and then hold and drag to select the rest of the lines.
- write `/ask "..."` in the comment box and press `Add single comment` button.
-{width=512}
+
Note that the tool does not have "memory" of previous questions, and answers each question independently.
@@ -44,19 +49,19 @@ To get a direct link to an image, we recommend using the following scheme:
1\. First, post a comment that contains **only** the image:
-{width=512}
+
2\. Quote reply to that comment:
-{width=512}
+
3\. In the screen opened, type the question below the image:
-{width=512}
-{width=512}
+
+
4\. Post the comment, and receive the answer:
-{width=512}
+
See a full video tutorial [here](https://codium.ai/images/pr_agent/ask_image_video.mov)
diff --git a/docs/docs/tools/describe.md b/docs/docs/tools/describe.md
index 8b3598de5b..dfb9b89b0c 100644
--- a/docs/docs/tools/describe.md
+++ b/docs/docs/tools/describe.md
@@ -1,3 +1,8 @@
+---
+title: "Describe"
+sidebar_position: 2
+---
+
## Overview
The `describe` tool scans the PR code changes, and generates a description for the PR - title, type, summary, walkthrough and labels.
@@ -14,11 +19,11 @@ The tool can be triggered automatically every time a new PR is [opened](../usage
Invoke the tool manually by commenting `/describe` on any PR:
-{width=512}
+
After ~30 seconds, the tool will generate a description for the PR:
-{width=512}
+
If you want to edit [configurations](#configuration-options), add the relevant ones to the command:
@@ -59,7 +64,7 @@ From our experience, there are two possible reasons:
- When _updating_ PR descriptions, the `/describe` tool considers everything above the "PR Type" field as user content and will preserve it.
Everything below this marker is treated as previously auto-generated content and will be replaced.
-{width=512}
+
## Sequence Diagram Support
The `/describe` tool includes a Mermaid sequence diagram showing component/function interactions.
@@ -85,70 +90,74 @@ This option is enabled by default via the `pr_description.enable_pr_diagram` par
## Configuration options
-???+ example "Possible configurations"
-
- | publish_labels | -If set to true, the tool will publish labels to the PR. Default is false. | -
| publish_description_as_comment | -If set to true, the tool will publish the description as a comment to the PR. If false, it will overwrite the original description. Default is false. | -
| publish_description_as_comment_persistent | -If set to true and `publish_description_as_comment` is true, the tool will publish the description as a persistent comment to the PR. Default is true. | -
| add_original_user_description | -If set to true, the tool will add the original user description to the generated description. Default is true. | -
| generate_ai_title | -If set to true, the tool will also generate an AI title for the PR. Default is false. | -
| extra_instructions | -Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ..." | -
| enable_pr_type | -If set to false, it will not show the `PR type` as a text value in the description content. Default is true. | -
| final_update_message | -If set to true, it will add a comment message [`PR Description updated to latest commit...`](https://github.com/qodo-ai/pr-agent/pull/499#issuecomment-1837412176) after finishing calling `/describe`. Default is true. | -
| enable_semantic_files_types | -If set to true, "Changes walkthrough" section will be generated. Default is true. | -
| file_table_collapsible_open_by_default | -If set to true, the file list in the "Changes walkthrough" section will be open by default. If set to false, it will be closed by default. Default is false. | -
| collapsible_file_list | -If set to true, the file list in the "Changes walkthrough" section will be collapsible. If set to "adaptive", the file list will be collapsible only if there are more than 8 files. Default is "adaptive". | -
| enable_large_pr_handling | -If set to true, in case of a large PR the tool will make several calls to the AI and combine them to be able to cover more files. Default is true. | -
| enable_help_text | -If set to true, the tool will display a help text in the comment. Default is false. | -
| enable_pr_diagram | -If set to true, the tool will generate a horizontal Mermaid flowchart summarizing the main pull request changes. This field remains empty if not applicable. Default is true. | -
| auto_create_ticket | -If set to true, this will automatically create a ticket in the ticketing system when a PR is opened. Default is false. | -
| publish_labels | +If set to true, the tool will publish labels to the PR. Default is false. | +
| publish_description_as_comment | +If set to true, the tool will publish the description as a comment to the PR. If false, it will overwrite the original description. Default is false. | +
| publish_description_as_comment_persistent | +If set to true and `publish_description_as_comment` is true, the tool will publish the description as a persistent comment to the PR. Default is true. | +
| add_original_user_description | +If set to true, the tool will add the original user description to the generated description. Default is true. | +
| generate_ai_title | +If set to true, the tool will also generate an AI title for the PR. Default is false. | +
| extra_instructions | +Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ..." | +
| enable_pr_type | +If set to false, it will not show the `PR type` as a text value in the description content. Default is true. | +
| final_update_message | +If set to true, it will add a comment message [`PR Description updated to latest commit...`](https://github.com/qodo-ai/pr-agent/pull/499#issuecomment-1837412176) after finishing calling `/describe`. Default is true. | +
| enable_semantic_files_types | +If set to true, "Changes walkthrough" section will be generated. Default is true. | +
| file_table_collapsible_open_by_default | +If set to true, the file list in the "Changes walkthrough" section will be open by default. If set to false, it will be closed by default. Default is false. | +
| collapsible_file_list | +If set to true, the file list in the "Changes walkthrough" section will be collapsible. If set to "adaptive", the file list will be collapsible only if there are more than 8 files. Default is "adaptive". | +
| enable_large_pr_handling | +If set to true, in case of a large PR the tool will make several calls to the AI and combine them to be able to cover more files. Default is true. | +
| enable_help_text | +If set to true, the tool will display a help text in the comment. Default is false. | +
| enable_pr_diagram | +If set to true, the tool will generate a horizontal Mermaid flowchart summarizing the main pull request changes. This field remains empty if not applicable. Default is true. | +
| auto_create_ticket | +If set to true, this will automatically create a ticket in the ticketing system when a PR is opened. Default is false. | +
becomes
-{width=512}
+
**Configuration params**:
@@ -197,8 +206,12 @@ Custom labels can be defined in a configuration file, or directly in the repo's
Make sure to provide proper title, and a detailed and well-phrased description for each label, so the tool will know when to suggest it.
Each label description should be a **conditional statement**, that indicates if to add the label to the PR or not, according to the PR content.
-???+ tip "Auto-remove custom label when no longer relevant"
- If the custom label is no longer relevant, it will be automatically removed from the PR by running the `generate_labels` tool or the `describe` tool.
+
## Usage Tips
-!!! tip "Automation"
- - When you first install PR-Agent app, the [default mode](../usage-guide/automations_and_usage.md#github-app) for the describe tool is:
- ```
- pr_commands = ["/describe", ...]
- ```
- meaning the `describe` tool will run automatically on every PR, with the default configurations.
+:::tip[Automation]
+- When you first install PR-Agent app, the [default mode](../usage-guide/automations_and_usage.md#github-app) for the describe tool is:
+```
+pr_commands = ["/describe", ...]
+```
+meaning the `describe` tool will run automatically on every PR, with the default configurations.
+:::
- Markers are an alternative way to control the generated description, to give maximal control to the user. If you set:
diff --git a/docs/docs/tools/generate_labels.md b/docs/docs/tools/generate_labels.md
index fcbbe3b75d..0f16af8926 100644
--- a/docs/docs/tools/generate_labels.md
+++ b/docs/docs/tools/generate_labels.md
@@ -1,3 +1,8 @@
+---
+title: "Generate Labels"
+sidebar_position: 7
+---
+
## Overview
The `generate_labels` tool scans the PR code changes and generates custom labels for the PR based on the content and context of the changes.
@@ -12,11 +17,11 @@ It can be invoked manually by commenting on any PR:
Invoke the tool manually by commenting `/generate_labels` on any PR:
-{width=512}
+
The tool will analyze the PR and add appropriate labels:
-{width=512}
+
## Configuration options
diff --git a/docs/docs/tools/help.md b/docs/docs/tools/help.md
index 900587f772..28a01e95d7 100644
--- a/docs/docs/tools/help.md
+++ b/docs/docs/tools/help.md
@@ -1,3 +1,8 @@
+---
+title: "Help"
+sidebar_position: 9
+---
+
## Overview
The `help` tool provides a list of all the available tools and their descriptions.
@@ -13,9 +18,9 @@ It can be invoked manually by commenting on any PR:
Invoke the `help` tool by commenting on a PR with:
-{width=750}
+
Response will include a list of available tools:
-{width=750}
+
diff --git a/docs/docs/tools/help_docs.md b/docs/docs/tools/help_docs.md
index f0a71912e9..d73f6fd671 100644
--- a/docs/docs/tools/help_docs.md
+++ b/docs/docs/tools/help_docs.md
@@ -1,3 +1,8 @@
+---
+title: "Help Docs"
+sidebar_position: 10
+---
+
## Overview
The `help_docs` tool can answer a free-text question based on a git documentation folder.
@@ -8,7 +13,7 @@ It can be invoked manually by commenting on any PR or Issue:
/help_docs "..."
```
-Or configured to be triggered automatically when a [new issue is opened](#run-as-a-github-action).
+Or configured to be triggered automatically when a [new issue is opened](#run-automatically-when-a-new-issue-is-opened).
The tool assumes by default that the documentation is located in the root of the repository, at `/docs` folder.
However, this can be customized by setting the `docs_path` configuration option:
@@ -31,11 +36,11 @@ See more configuration options in the [Configuration options](#configuration-opt
**Asking a question about another repository**
-{width=512}
+
**Response**:
-{width=512}
+
## Run automatically when a new issue is opened
diff --git a/docs/docs/tools/improve.md b/docs/docs/tools/improve.mdx
similarity index 58%
rename from docs/docs/tools/improve.md
rename to docs/docs/tools/improve.mdx
index 11f3b9cf9b..2a2dd96acc 100644
--- a/docs/docs/tools/improve.md
+++ b/docs/docs/tools/improve.mdx
@@ -1,3 +1,11 @@
+---
+title: "Improve"
+sidebar_position: 4
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Overview
The `improve` tool scans the PR code changes, and automatically generates meaningful suggestions for improving the PR code.
@@ -9,11 +17,18 @@ The tool can be triggered automatically every time a new PR is [opened](../usage
## How it looks
-=== "Suggestions Overview"
- {width=512}
+
+
+
+
+
### Automatic triggering
@@ -75,7 +90,7 @@ The table format offers several key advantages:
Table mode is the default of PR-Agent, and is recommended approach for most users due to these benefits.
-{width=512}
+
Teams with specific preferences can enable committable code comments mode in their local configuration, or use [dual publishing mode](#dual-publishing-mode).
@@ -111,61 +126,68 @@ Use triple quotes to write multi-line instructions. Use bullet points or numbers
PR-Agent supports both simple and hierarchical best practices configurations to provide guidance to the AI model for generating relevant code suggestions.
-???- tip "Writing effective best practices files"
-
- The following guidelines apply to all best practices files:
-
- - Write clearly and concisely
- - Include brief code examples when helpful with before/after patterns
- - Focus on project-specific guidelines that will result in relevant suggestions you actually want to get
- - Keep each file relatively short, under 800 lines, since:
- - AI models may not process effectively very long documents
- - Long files tend to contain generic guidelines already known to AI
- - Maximum multiple file accumulated content is limited to 2000 lines.
- - Use pattern-based structure rather than simple bullet points for better clarity
-
-???- tip "Example of a best practices file"
-
- Pattern 1: Add proper error handling with try-except blocks around external function calls.
-
- Example code before:
-
- ```python
+
-!!! tip "Tip - Reducing visual footprint after self-review"
+:::tip[Tip - Reducing visual footprint after self-review]
- The configuration parameter `pr_code_suggestions.fold_suggestions_on_self_review` (default is True)
- can be used to automatically fold the suggestions after the user clicks the self-review checkbox.
+The configuration parameter `pr_code_suggestions.fold_suggestions_on_self_review` (default is True)
+can be used to automatically fold the suggestions after the user clicks the self-review checkbox.
- This reduces the visual footprint of the suggestions, and also indicates to the PR reviewer that the suggestions have been reviewed by the PR author, and don't require further attention.
+This reduces the visual footprint of the suggestions, and also indicates to the PR reviewer that the suggestions have been reviewed by the PR author, and don't require further attention.
+:::
-!!! tip "Tip - Demanding self-review from the PR author"
+:::tip[Tip - Demanding self-review from the PR author]
- By setting:
- ```toml
- [pr_code_suggestions]
- approve_pr_on_self_review = true
- ```
- the tool can automatically add an approval when the PR author clicks the self-review checkbox.
+By setting:
+```toml
+[pr_code_suggestions]
+approve_pr_on_self_review = true
+```
+the tool can automatically add an approval when the PR author clicks the self-review checkbox.
- - If you set the number of required reviewers for a PR to 2, this effectively means that the PR author must click the self-review checkbox before the PR can be merged (in addition to a human reviewer).
+- If you set the number of required reviewers for a PR to 2, this effectively means that the PR author must click the self-review checkbox before the PR can be merged (in addition to a human reviewer).
- {width=512}
+
- - If you keep the number of required reviewers for a PR to 1 and enable this configuration, this effectively means that the PR author can approve the PR by actively clicking the self-review checkbox.
+- If you keep the number of required reviewers for a PR to 1 and enable this configuration, this effectively means that the PR author can approve the PR by actively clicking the self-review checkbox.
- To prevent unauthorized approvals, this configuration defaults to false, and cannot be altered through online comments; enabling requires a direct update to the configuration file and a commit to the repository. This ensures that utilizing the feature demands a deliberate documented decision by the repository owner.
+ To prevent unauthorized approvals, this configuration defaults to false, and cannot be altered through online comments; enabling requires a direct update to the configuration file and a commit to the repository. This ensures that utilizing the feature demands a deliberate documented decision by the repository owner.
+:::
### How many code suggestions are generated?
@@ -281,59 +305,67 @@ Note: Chunking is primarily relevant for large PRs. For most PRs (up to 600 line
## Configuration options
-???+ example "General options"
-
- | extra_instructions | -Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...". | -
| commitable_code_suggestions | -If set to true, the tool will display the suggestions as committable code comments. Default is false. | -
| dual_publishing_score_threshold | -Minimum score threshold for suggestions to be presented as committable PR comments in addition to the table. Default is -1 (disabled). | -
| focus_only_on_problems | -If set to true, suggestions will focus primarily on identifying and fixing code problems, and less on style considerations like best practices, maintainability, or readability. Default is true. | -
| persistent_comment | -If set to true, the improve comment will be persistent, meaning that every new improve request will edit the previous one. Default is true. | -
| suggestions_score_threshold | -Any suggestion with importance score less than this threshold will be removed. Default is 0. Highly recommend not to set this value above 7-8, since above it may clip relevant suggestions that can be useful. | -
| enable_help_text | -If set to true, the tool will display a help text in the comment. Default is false. | -
| enable_chat_text | -If set to true, the tool will display a reference to the PR chat in the comment. Default is false. | -
| publish_output_no_suggestions | -If set to true, the tool will publish a comment even if no suggestions were found. Default is true. | -
| num_code_suggestions_per_chunk | -Number of code suggestions provided by the 'improve' tool, per chunk. Default is 3. | -
| max_number_of_calls | -Maximum number of chunks. Default is 3. | -
| extra_instructions | +Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...". | +
| commitable_code_suggestions | +If set to true, the tool will display the suggestions as committable code comments. Default is false. | +
| dual_publishing_score_threshold | +Minimum score threshold for suggestions to be presented as committable PR comments in addition to the table. Default is -1 (disabled). | +
| focus_only_on_problems | +If set to true, suggestions will focus primarily on identifying and fixing code problems, and less on style considerations like best practices, maintainability, or readability. Default is true. | +
| persistent_comment | +If set to true, the improve comment will be persistent, meaning that every new improve request will edit the previous one. Default is true. | +
| suggestions_score_threshold | +Any suggestion with importance score less than this threshold will be removed. Default is 0. Highly recommend not to set this value above 7-8, since above it may clip relevant suggestions that can be useful. | +
| enable_help_text | +If set to true, the tool will display a help text in the comment. Default is false. | +
| enable_chat_text | +If set to true, the tool will display a reference to the PR chat in the comment. Default is false. | +
| publish_output_no_suggestions | +If set to true, the tool will publish a comment even if no suggestions were found. Default is true. | +
| num_code_suggestions_per_chunk | +Number of code suggestions provided by the 'improve' tool, per chunk. Default is 3. | +
| max_number_of_calls | +Maximum number of chunks. Default is 3. | +
After ~30 seconds, the tool will generate a review for the PR:
-{width=512}
+
If you want to edit [configurations](#configuration-options), add the relevant ones to the command:
@@ -51,147 +56,164 @@ extra_instructions = "..."
## Configuration options
-???+ example "General options"
-
- | persistent_comment | -If set to true, the review comment will be persistent, meaning that every new review request will edit the previous one. Default is true. | -
| final_update_message | -When set to true, updating a persistent review comment during online commenting will automatically add a short comment with a link to the updated review in the pull request .Default is true. | -
| extra_instructions | -Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...". | -
| enable_help_text | -If set to true, the tool will display a help text in the comment. Default is false. | -
| num_max_findings | -Number of maximum returned findings. Default is 3. | -
| require_score_review | -If set to true, the tool will add a section that scores the PR. Default is false. | -
| require_tests_review | -If set to true, the tool will add a section that checks if the PR contains tests. Default is true. | -
| require_estimate_effort_to_review | -If set to true, the tool will add a section that estimates the effort needed to review the PR. Default is true. | -
| require_estimate_contribution_time_cost | -If set to true, the tool will add a section that estimates the time required for a senior developer to create and submit such changes. Default is false. | -
| require_can_be_split_review | -If set to true, the tool will add a section that checks if the PR contains several themes, and can be split into smaller PRs. Default is false. | -
| require_security_review | -If set to true, the tool will add a section that checks if the PR contains a possible security or vulnerability issue. Default is true. | -
| require_todo_scan | -If set to true, the tool will add a section that lists TODO comments found in the PR code changes. Default is false. - | -
| require_ticket_analysis_review | -If set to true, and the PR contains a GitHub or Jira ticket link, the tool will add a section that checks if the PR in fact fulfilled the ticket requirements. Default is true. | -
| enable_review_labels_security | -If set to true, the tool will publish a 'possible security issue' label if it detects a security issue. Default is true. | -
| enable_review_labels_effort | -If set to true, the tool will publish a 'Review effort x/5' label (1–5 scale). Default is true. | -
| persistent_comment | +If set to true, the review comment will be persistent, meaning that every new review request will edit the previous one. Default is true. | +
| final_update_message | +When set to true, updating a persistent review comment during online commenting will automatically add a short comment with a link to the updated review in the pull request .Default is true. | +
| extra_instructions | +Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...". | +
| enable_help_text | +If set to true, the tool will display a help text in the comment. Default is false. | +
| num_max_findings | +Number of maximum returned findings. Default is 3. | +
| require_score_review | +If set to true, the tool will add a section that scores the PR. Default is false. | +
| require_tests_review | +If set to true, the tool will add a section that checks if the PR contains tests. Default is true. | +
| require_estimate_effort_to_review | +If set to true, the tool will add a section that estimates the effort needed to review the PR. Default is true. | +
| require_estimate_contribution_time_cost | +If set to true, the tool will add a section that estimates the time required for a senior developer to create and submit such changes. Default is false. | +
| require_can_be_split_review | +If set to true, the tool will add a section that checks if the PR contains several themes, and can be split into smaller PRs. Default is false. | +
| require_security_review | +If set to true, the tool will add a section that checks if the PR contains a possible security or vulnerability issue. Default is true. | +
| require_todo_scan | +If set to true, the tool will add a section that lists TODO comments found in the PR code changes. Default is false. + | +
| require_ticket_analysis_review | +If set to true, and the PR contains a GitHub or Jira ticket link, the tool will add a section that checks if the PR in fact fulfilled the ticket requirements. Default is true. | +
| enable_review_labels_security | +If set to true, the tool will publish a 'possible security issue' label if it detects a security issue. Default is true. | +
| enable_review_labels_effort | +If set to true, the tool will publish a 'Review effort x/5' label (1–5 scale). Default is true. | +
-{width=768}
+
-{width=768}
+
Note that to perform retrieval, the `similar_issue` tool indexes all the repo previous issues (once).
diff --git a/docs/docs/tools/update_changelog.md b/docs/docs/tools/update_changelog.md
index 11a55769bc..4c9d30c610 100644
--- a/docs/docs/tools/update_changelog.md
+++ b/docs/docs/tools/update_changelog.md
@@ -1,3 +1,8 @@
+---
+title: "Update Changelog"
+sidebar_position: 11
+---
+
## Overview
The `update_changelog` tool automatically updates the CHANGELOG.md file with the PR changes.
@@ -9,9 +14,9 @@ It can be invoked manually by commenting on any PR:
## Example usage
-{width=768}
+
-{width=768}
+
## Configuration options
diff --git a/docs/docs/usage-guide/EXAMPLE_BEST_PRACTICE.md b/docs/docs/usage-guide/EXAMPLE_BEST_PRACTICE.md
index 993c0246db..f0095d1306 100644
--- a/docs/docs/usage-guide/EXAMPLE_BEST_PRACTICE.md
+++ b/docs/docs/usage-guide/EXAMPLE_BEST_PRACTICE.md
@@ -1,3 +1,8 @@
+---
+title: "Example Best Practice"
+sidebar_position: 8
+---
+
## Recommend Python Best Practices
This document outlines a series of recommended best practices for Python development. These guidelines aim to improve code quality, maintainability, and readability.
diff --git a/docs/docs/usage-guide/additional_configurations.md b/docs/docs/usage-guide/additional_configurations.md
index d1684487d5..4b7b395da7 100644
--- a/docs/docs/usage-guide/additional_configurations.md
+++ b/docs/docs/usage-guide/additional_configurations.md
@@ -1,6 +1,11 @@
+---
+title: "Additional Configurations"
+sidebar_position: 7
+---
+
## Show possible configurations
-The possible configurations of PR-Agent are stored in [here](https://github.com/qodo-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml){:target="_blank"}.
+The possible configurations of PR-Agent are stored in [here](https://github.com/qodo-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml).
In the [tools](../tools/index.md) page you can find explanations on how to use these configurations for each tool.
To print all the available configurations as a comment on your PR, you can use the following command:
@@ -9,7 +14,7 @@ To print all the available configurations as a comment on your PR, you can use t
/config
```
-{width=512}
+
To view the **actual** configurations used for a specific tool, after all the user settings are applied, you can add for each tool a `--config.output_relevant_configurations=true` suffix.
For example:
@@ -20,7 +25,7 @@ For example:
Will output an additional field showing the actual configurations used for the `improve` tool.
-{width=512}
+
## Ignoring files from analysis
@@ -93,7 +98,7 @@ This will set the response language globally for all the commands to Italian.
[//]: # (1) [Use a model](./changing_a_model.md) with larger context, like GPT-32K, or claude-100K. This solution will be applicable for all the tools.)
-[//]: # (2) For the `/improve` tool, there is an ['extended' mode](../tools/improve.md) (`/improve --extended`),)
+[//]: # (2) For the `/improve` tool, there is an ['extended' mode](../tools/improve.mdx) (`/improve --extended`),)
[//]: # (which divides the PR into chunks, and processes each chunk separately. With this mode, regardless of the model, no compression will be done (but for large PRs, multiple model calls may occur))
@@ -253,8 +258,9 @@ ignore_pr_authors = ["my-special-bot-user", ...]
Where the `ignore_pr_authors` is a regex list of usernames that you want to ignore.
-!!! note
- There is one specific case where bots will receive an automatic response - when they generated a PR with a _failed test_.
+:::note
+There is one specific case where bots will receive an automatic response - when they generated a PR with a _failed test_.
+:::
### Ignoring Generated Files by Language/Framework
diff --git a/docs/docs/usage-guide/automations_and_usage.md b/docs/docs/usage-guide/automations_and_usage.md
index c7355d5dbf..98e03ffd5a 100644
--- a/docs/docs/usage-guide/automations_and_usage.md
+++ b/docs/docs/usage-guide/automations_and_usage.md
@@ -1,3 +1,8 @@
+---
+title: "Usage and Automation"
+sidebar_position: 4
+---
+
## Local repo (CLI)
When running from your locally cloned PR-Agent repo (CLI), your local configuration file will be used.
@@ -90,9 +95,10 @@ When this parameter is set to `true`, PR-Agent will not run any automatic tools
### GitHub App
-!!! note "Configurations for PR-Agent"
- PR-Agent for GitHub is an App, hosted by Codium. So all the instructions below are relevant for PR-Agent users.
- Same goes for [GitLab webhook](#gitlab-webhook) and [BitBucket App](#bitbucket-app) sections.
+:::note[Configurations for PR-Agent]
+PR-Agent for GitHub is an App, hosted by Codium. So all the instructions below are relevant for PR-Agent users.
+Same goes for [GitLab webhook](#gitlab-webhook) and [BitBucket App](#bitbucket-app) sections.
+:::
#### GitHub app automatic tools when a new PR is opened
diff --git a/docs/docs/usage-guide/changing_a_model.md b/docs/docs/usage-guide/changing_a_model.md
index 140a16c612..ed5bbd86f7 100644
--- a/docs/docs/usage-guide/changing_a_model.md
+++ b/docs/docs/usage-guide/changing_a_model.md
@@ -1,3 +1,8 @@
+---
+title: "Changing a Model"
+sidebar_position: 6
+---
+
## Changing a model in PR-Agent
See [here](https://github.com/qodo-ai/pr-agent/blob/main/pr_agent/algo/__init__.py) for a list of supported models in PR-Agent.
@@ -13,9 +18,10 @@ fallback_models = ["..."]
For models and environments not from OpenAI, you might need to provide additional keys and other parameters.
You can give parameters via a configuration file, or from environment variables.
-!!! note "Model-specific environment variables"
- See [litellm documentation](https://litellm.vercel.app/docs/proxy/quick_start#supported-llms) for the environment variables needed per model, as they may vary and change over time. Our documentation per-model may not always be up-to-date with the latest changes.
- Failing to set the needed keys of a specific model will usually result in litellm not identifying the model type, and failing to utilize it.
+:::note[Model-specific environment variables]
+See [litellm documentation](https://litellm.vercel.app/docs/proxy/quick_start#supported-llms) for the environment variables needed per model, as they may vary and change over time. Our documentation per-model may not always be up-to-date with the latest changes.
+Failing to set the needed keys of a specific model will usually result in litellm not identifying the model type, and failing to utilize it.
+:::
### OpenAI like API
To use an OpenAI like API, set the following in your `.secrets.toml` file:
@@ -105,14 +111,15 @@ By default, Ollama uses a context window size of 2048 tokens. In most cases this
Please note that the `custom_model_max_tokens` setting should be configured in accordance with the `OLLAMA_CONTEXT_LENGTH`. Failure to do so may result in unexpected model output.
-!!! note "Local models vs commercial models"
- PR-Agent is compatible with almost any AI model, but analyzing complex code repositories and pull requests requires a model specifically optimized for code analysis.
+:::note[Local models vs commercial models]
+PR-Agent is compatible with almost any AI model, but analyzing complex code repositories and pull requests requires a model specifically optimized for code analysis.
+
+Commercial models such as GPT-5, Claude Sonnet, and Gemini have demonstrated robust capabilities in generating structured output for code analysis tasks with large input. In contrast, most open-source models currently available (as of January 2025) face challenges with these complex tasks.
- Commercial models such as GPT-5, Claude Sonnet, and Gemini have demonstrated robust capabilities in generating structured output for code analysis tasks with large input. In contrast, most open-source models currently available (as of January 2025) face challenges with these complex tasks.
+Based on our testing, local open-source models are suitable for experimentation and learning purposes (mainly for the `ask` command), but they are not suitable for production-level code analysis tasks.
- Based on our testing, local open-source models are suitable for experimentation and learning purposes (mainly for the `ask` command), but they are not suitable for production-level code analysis tasks.
-
- Hence, for production workflows and real-world usage, we recommend using commercial models.
+Hence, for production workflows and real-world usage, we recommend using commercial models.
+:::
### Hugging Face
diff --git a/docs/docs/usage-guide/configuration_options.md b/docs/docs/usage-guide/configuration_options.md
index 1e48ccdda9..6457644208 100644
--- a/docs/docs/usage-guide/configuration_options.md
+++ b/docs/docs/usage-guide/configuration_options.md
@@ -1,3 +1,8 @@
+---
+title: "Configuration File"
+sidebar_position: 3
+---
+
The different tools and sub-tools used by PR-Agent are adjustable via a Git configuration file.
There are three main ways to set persistent configurations:
@@ -11,10 +16,12 @@ In terms of precedence, wiki configurations will override local configurations,
For a list of all possible configurations, see the [configuration options](https://github.com/qodo-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml) page.
In addition to general configuration options, each tool has its own configurations. For example, the `review` tool will use parameters from the [pr_reviewer](https://github.com/qodo-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L66) section in the configuration file.
-!!! tip "Tip1: Edit only what you need"
- Your configuration file should be minimal, and edit only the relevant values. Don't copy the entire configuration options, since it can lead to legacy problems when something changes.
-!!! tip "Tip2: Show relevant configurations"
- If you set `config.output_relevant_configurations` to True, each tool will also output in a collapsible section its relevant configurations. This can be useful for debugging, or getting to know the configurations better.
+:::tip[Tip1: Edit only what you need]
+Your configuration file should be minimal, and edit only the relevant values. Don't copy the entire configuration options, since it can lead to legacy problems when something changes.
+:::
+:::tip[Tip2: Show relevant configurations]
+If you set `config.output_relevant_configurations` to True, each tool will also output in a collapsible section its relevant configurations. This can be useful for debugging, or getting to know the configurations better.
+:::
@@ -25,7 +32,7 @@ In addition to general configuration options, each tool has its own configuratio
With PR-Agent, you can set configurations by creating a page called `.pr_agent.toml` in the [wiki](https://github.com/qodo-ai/pr-agent/wiki/pr_agent.toml) of the repo.
The advantage of this method is that it allows to set configurations without needing to commit new content to the repo - just edit the wiki page and **save**.
-{width=512}
+
Click [here](https://codium.ai/images/pr_agent/wiki_configuration_pr_agent.mp4) to see a short instructional video. We recommend surrounding the configuration content with triple-quotes (or \`\`\`toml), to allow better presentation when displayed in the wiki as markdown.
An example content:
@@ -76,8 +83,9 @@ For example, in the GitHub organization `qodo-ai`:
Create a repository named `pr-agent-settings` within a specific project (Bitbucket) or a group/subgroup (Gitlab).
The configuration file in this repository will apply to all repositories directly under the same project/group/subgroup.
-!!! note "Note"
- For Gitlab, in case of a repository nested in several sub groups, the lookup for a pr-agent-settings repo will be only on one level above such repository.
+:::note[Note]
+For Gitlab, in case of a repository nested in several sub groups, the lookup for a pr-agent-settings repo will be only on one level above such repository.
+:::
## Organization level configuration file
@@ -91,9 +99,10 @@ Create a dedicated project to hold a global configuration file that affects all
1. Create a new project with both the name and key: PR_AGENT_SETTINGS.
2. Inside the PR_AGENT_SETTINGS project, create a repository named pr-agent-settings.
3. In this repository, add a `.pr_agent.toml` configuration file—structured similarly to the global configuration file described above.
-4. Optionally, you can add organizational-level [global best practices](../tools/improve.md#global-hierarchical-best-practices).
+4. Optionally, you can add organizational-level [global best practices](../tools/improve.mdx#best-practices).
Repositories across your entire Bitbucket organization will inherit the configuration from this file.
-!!! note "Note"
- If both organization-level and project-level global settings are defined, the project-level settings will take precedence over the organization-level configuration. Additionally, parameters from a repository’s local .pr_agent.toml file will always override both global settings.
+:::note[Note]
+If both organization-level and project-level global settings are defined, the project-level settings will take precedence over the organization-level configuration. Additionally, parameters from a repository’s local .pr_agent.toml file will always override both global settings.
+:::
diff --git a/docs/docs/usage-guide/index.md b/docs/docs/usage-guide/index.md
index bb08ee6f1c..764a55c012 100644
--- a/docs/docs/usage-guide/index.md
+++ b/docs/docs/usage-guide/index.md
@@ -1,3 +1,8 @@
+---
+title: "Usage Guide"
+sidebar_position: 1
+---
+
# Usage guide
This section provides a detailed guide on how to use PR-Agent.
@@ -19,6 +24,6 @@ It includes information on how to adjust PR-Agent configurations, define which t
- [Additional Configurations](./additional_configurations.md)
- [Ignoring files from analysis](./additional_configurations.md#ignoring-files-from-analysis)
- [Extra instructions](./additional_configurations.md#extra-instructions)
- - [Working with large PRs](./additional_configurations.md#working-with-large-prs)
+ - [Working with large PRs](./additional_configurations.md)
- [Changing a model](./changing_a_model.md)
- [FAQ](../faq/index.md)
diff --git a/docs/docs/usage-guide/introduction.md b/docs/docs/usage-guide/introduction.md
index 095375e7d5..52d6448300 100644
--- a/docs/docs/usage-guide/introduction.md
+++ b/docs/docs/usage-guide/introduction.md
@@ -1,10 +1,15 @@
+---
+title: "Introduction"
+sidebar_position: 2
+---
+
After [installation](../installation/index.md), there are three basic ways to invoke PR-Agent:
1. Locally running a CLI command
-2. Online usage - by [commenting](https://github.com/qodo-ai/pr-agent/pull/229#issuecomment-1695021901){:target="_blank"} on a PR
+2. Online usage - by [commenting](https://github.com/qodo-ai/pr-agent/pull/229#issuecomment-1695021901) on a PR
3. Enabling PR-Agent tools to run automatically when a new PR is opened
Specifically, CLI commands can be issued by invoking a pre-built [docker image](../installation/locally.md#using-docker-image), or by invoking a [locally cloned repo](../installation/locally.md#run-from-source).
-For online usage, you will need to setup either a [GitHub App](../installation/github.md#run-as-a-github-app) or a [GitHub Action](../installation/github.md#run-as-a-github-action) (GitHub), a [GitLab webhook](../installation/gitlab.md#run-a-gitlab-webhook-server) (GitLab), or a [BitBucket App](../installation/bitbucket.md#run-using-codiumai-hosted-bitbucket-app) (BitBucket).
+For online usage, you will need to setup either a [GitHub App](../installation/github.md#run-as-a-github-app) or a [GitHub Action](../installation/github.md#run-as-a-github-action) (GitHub), a [GitLab webhook](../installation/gitlab.md#run-a-gitlab-webhook-server) (GitLab), or a [BitBucket App](../installation/bitbucket.md) (BitBucket).
These platforms also enable to run PR-Agent specific tools automatically when a new PR is opened, or on each push to a branch.
diff --git a/docs/docs/usage-guide/mail_notifications.md b/docs/docs/usage-guide/mail_notifications.md
index ca6933be16..2f3e5c7dce 100644
--- a/docs/docs/usage-guide/mail_notifications.md
+++ b/docs/docs/usage-guide/mail_notifications.md
@@ -1,12 +1,17 @@
+---
+title: "Managing Mail Notifications"
+sidebar_position: 5
+---
+
Unfortunately, it is not possible in GitHub to disable mail notifications from a specific user.
If you are subscribed to notifications for a repo with PR-Agent, we recommend turning off notifications for PR comments, to avoid lengthy emails:
-{width=512}
+
As an alternative, you can filter in your mail provider the notifications specifically from the PR-Agent bot, [see how](https://www.quora.com/How-can-you-filter-emails-for-specific-people-in-Gmail#:~:text=On%20the%20Filters%20and%20Blocked,the%20body%20of%20the%20email).
-{width=512}
+
Another option to reduce the mail overload, yet still receive notifications on PR-Agent tools, is to disable the help collapsible section in PR-Agent bot comments.
This can done by setting `enable_help_text=false` for the relevant tool in the configuration file.
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
new file mode 100644
index 0000000000..0fd18ac92d
--- /dev/null
+++ b/docs/docusaurus.config.js
@@ -0,0 +1,132 @@
+// @ts-check
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+ title: 'PR-Agent',
+ tagline: 'AI-powered code review agent',
+ url: 'https://qodo-merge-docs.qodo.ai',
+ baseUrl: '/',
+ onBrokenLinks: 'throw',
+ onBrokenAnchors: 'warn',
+ favicon: 'img/favicon.svg',
+ organizationName: 'qodo-ai',
+ projectName: 'pr-agent',
+
+ markdown: {
+ format: 'detect',
+ hooks: {
+ onBrokenMarkdownLinks: 'throw',
+ },
+ },
+
+ presets: [
+ [
+ 'classic',
+ /** @type {import('@docusaurus/preset-classic').Options} */
+ ({
+ docs: {
+ routeBasePath: '/',
+ sidebarPath: require.resolve('./sidebars.js'),
+ editUrl: 'https://github.com/qodo-ai/pr-agent/tree/main/docs/',
+ },
+ blog: false,
+ theme: {
+ customCss: require.resolve('./src/css/custom.css'),
+ },
+ }),
+ ],
+ ],
+
+ plugins: [
+ [
+ '@docusaurus/plugin-google-tag-manager',
+ {
+ containerId: 'GTM-5C9KZBM3',
+ },
+ ],
+ ],
+
+ themes: [
+ [
+ '@easyops-cn/docusaurus-search-local',
+ /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
+ ({
+ hashed: true,
+ docsRouteBasePath: '/',
+ }),
+ ],
+ ],
+
+ themeConfig:
+ /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+ ({
+ navbar: {
+ title: 'PR-Agent',
+ logo: {
+ alt: 'PR-Agent Logo',
+ src: 'img/favicon.svg',
+ },
+ items: [
+ {
+ type: 'docSidebar',
+ sidebarId: 'getStarted',
+ label: 'Get Started',
+ position: 'left',
+ },
+ {
+ type: 'docSidebar',
+ sidebarId: 'tools',
+ label: 'Tools',
+ position: 'left',
+ },
+ {
+ type: 'docSidebar',
+ sidebarId: 'coreAbilities',
+ label: 'Core Abilities',
+ position: 'left',
+ },
+ {
+ type: 'docSidebar',
+ sidebarId: 'faq',
+ label: 'FAQ',
+ position: 'left',
+ },
+ {
+ href: 'https://github.com/qodo-ai/pr-agent',
+ label: 'GitHub',
+ position: 'right',
+ },
+ ],
+ },
+ announcementBar: {
+ id: 'announcement',
+ content:
+ 'Open source PR Agent documentation. For the Qodo free version, Get Started: https://www.qodo.ai/get-started/',
+ isCloseable: true,
+ },
+ colorMode: {
+ defaultMode: 'light',
+ respectPrefersColorScheme: true,
+ },
+ footer: {
+ style: 'dark',
+ links: [
+ {
+ title: 'Links',
+ items: [
+ {
+ label: 'GitHub',
+ href: 'https://github.com/qodo-ai/pr-agent',
+ },
+ ],
+ },
+ ],
+ copyright: `\u00a9 ${new Date().getFullYear()} PR-Agent Contributors`,
+ },
+ prism: {
+ additionalLanguages: ['toml', 'bash', 'yaml', 'python', 'json'],
+ },
+ }),
+};
+
+module.exports = config;
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
deleted file mode 100644
index 925ff818e5..0000000000
--- a/docs/mkdocs.yml
+++ /dev/null
@@ -1,125 +0,0 @@
-site_name: PR-Agent
-repo_url: https://github.com/qodo-ai/pr-agent
-repo_name: Qodo-ai/pr-agent
-
-nav:
- - Overview:
- - 'index.md'
- - Data Privacy: 'overview/data_privacy.md'
- - Installation:
- - 'installation/index.md'
- - PR-Agent: 'installation/pr_agent.md'
- - Usage Guide:
- - 'usage-guide/index.md'
- - Introduction: 'usage-guide/introduction.md'
- - Configuration File: 'usage-guide/configuration_options.md'
- - Usage and Automation: 'usage-guide/automations_and_usage.md'
- - Managing Mail Notifications: 'usage-guide/mail_notifications.md'
- - Changing a Model: 'usage-guide/changing_a_model.md'
- - Additional Configurations: 'usage-guide/additional_configurations.md'
- - Frequently Asked Questions: 'faq/index.md'
- - Tools:
- - 'tools/index.md'
- - Describe: 'tools/describe.md'
- - Review: 'tools/review.md'
- - Improve: 'tools/improve.md'
- - Ask: 'tools/ask.md'
- - Add Docs: 'tools/add_docs.md'
- - Generate Labels: 'tools/generate_labels.md'
- - Similar Issues: 'tools/similar_issues.md'
- - Help: 'tools/help.md'
- - Help Docs: 'tools/help_docs.md'
- - Update Changelog: 'tools/update_changelog.md'
- - Core Abilities:
- - 'core-abilities/index.md'
- - Compression strategy: 'core-abilities/compression_strategy.md'
- - Dynamic context: 'core-abilities/dynamic_context.md'
- - Fetching ticket context: 'core-abilities/fetching_ticket_context.md'
- - Interactivity: 'core-abilities/interactivity.md'
- - Local and global metadata: 'core-abilities/metadata.md'
- - Self-reflection: 'core-abilities/self_reflection.md'
-# - Code Fine-tuning Benchmark: 'finetuning_benchmark/index.md'
-
-theme:
- logo: assets/favicon.svg
- favicon: assets/favicon.svg
- name: material
- icon:
- repo: fontawesome/brands/github
- features:
- - navigation.tabs
- - navigation.expand
- - navigation.path
- - navigation.top
- - navigation.tracking
- - navigation.indexes
- - search.suggest
- - search.highlight
- - content.tabs.link
- - content.code.annotation
- - content.code.copy
- - announce.dismiss
- language: en
- custom_dir: overrides
-
- palette:
- - media: "(prefers-color-scheme)"
- toggle:
- icon: material/brightness-auto
- name: Switch to light mode
- - media: "(prefers-color-scheme: light)"
- scheme: default
- toggle:
- icon: material/toggle-switch-off-outline
- name: Switch to dark mode
- primary: custom
- accent: custom
- - media: "(prefers-color-scheme: dark)"
- scheme: slate
- toggle:
- icon: material/toggle-switch
- name: Switch to light mode
- primary: custom
- accent: custom
-
-plugins:
- - social
- - search
- - glightbox
-
-extra:
- generator: false
- social:
- - icon: fontawesome/brands/github
- link: https://github.com/qodo-ai/pr-agent
-
-extra_css:
- - css/custom.css
-
-markdown_extensions:
- - pymdownx.highlight:
- anchor_linenums: true
- - pymdownx.inlinehilite
- - pymdownx.snippets
- - admonition
- - pymdownx.arithmatex:
- generic: true
- - footnotes
- - pymdownx.details
- - pymdownx.superfences
- - pymdownx.mark
- - md_in_html
- - attr_list
- - pymdownx.emoji:
- emoji_index: !!python/name:material.extensions.emoji.twemoji
- emoji_generator: !!python/name:material.extensions.emoji.to_svg
- - pymdownx.tabbed:
- alternate_style: true
- - toc:
- title: On this page
- toc_depth: 3
- permalink: true
-
-
-copyright: |
- © 2026 PR-Agent Contributors
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
deleted file mode 100644
index 9bf3ed0558..0000000000
--- a/docs/overrides/main.html
+++ /dev/null
@@ -1,14 +0,0 @@
-{% extends "base.html" %}
-
-{% block announce %}
- Open source PR Agent documentation. For the Qodo free version, Get Started: https://www.qodo.ai/get-started/
-{% endblock %}
-
-{% block scripts %}
- {{ super() }}
-
-
-
-
-{% endblock %}
diff --git a/docs/overrides/partials/footer.html b/docs/overrides/partials/footer.html
deleted file mode 100644
index 981798ffa8..0000000000
--- a/docs/overrides/partials/footer.html
+++ /dev/null
@@ -1,98 +0,0 @@
-
-
-
-
-
-