Merge pull request #1194 from Codium-ai/tr/updates

docs: update PR-Agent Pro documentation with new features and improve…
Codium-ai · Sep 1, 2024 · 6e6151d · 6e6151d
2 parents 2448281 + e468efb
commit 6e6151d
Show file tree

Hide file tree

Showing 3 changed files with 56 additions and 30 deletions.
diff --git a/README.md b/README.md
@@ -47,9 +47,9 @@ CodiumAI PR-Agent aims to help efficiently review and handle pull requests, by p
 
 New version of [PR Agent Chrom Extension](https://chromewebstore.google.com/detail/pr-agent-chrome-extension/ephlnjeghhogofkifjloamocljapahnl) was released, with full support of context-aware **PR Chat**. This novel feature is free to use for any open-source repository. See more details in [here](https://pr-agent-docs.codium.ai/chrome-extension/#pr-chat).
 
-<kbd><img src="https://www.codium.ai/images/pr_agent/pr_chat1.png" width="768"></kbd>
+<kbd><img src="https://www.codium.ai/images/pr_agent/pr_chat_1.png" width="768"></kbd>
 
-<kbd><img src="https://www.codium.ai/images/pr_agent/pr_chat2.png" width="768"></kbd>
+<kbd><img src="https://www.codium.ai/images/pr_agent/pr_chat_2.png" width="768"></kbd>
 
 
 ### August 11, 2024

diff --git a/docs/docs/overview/pr_agent_pro.md b/docs/docs/overview/pr_agent_pro.md
@@ -7,25 +7,30 @@ PR-Agent Pro is designed for companies and teams that require additional feature
 
 3. **Improved support** - PR-Agent Pro users will receive priority support, and will be able to request new features and capabilities.
 
-4. **Additional tools**
-     - [**Custom Prompt Suggestions**](https://pr-agent-docs.codium.ai/tools/custom_prompt/)
-     - [**Tests**](https://pr-agent-docs.codium.ai/tools/test/)
-     - [**PR documentation**](https://pr-agent-docs.codium.ai/tools/documentation/)
-     - [**Improve Component**](https://pr-agent-docs.codium.ai/tools/improve_component/)
-     - [**Similar code search**](https://pr-agent-docs.codium.ai/tools/similar_code/)
-     - [**CI feedback**](https://pr-agent-docs.codium.ai/tools/ci_feedback/)
-     - [**Analyze PR components**](https://pr-agent-docs.codium.ai/tools/analyze/)
-
-
-5. **Additional features**
-     - [**Global and wiki configuration**](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/)
-     - [**Interactive triggering**](https://pr-agent-docs.codium.ai/tools/analyze/#overview)
-     - [**Apply suggestions**](https://pr-agent-docs.codium.ai/tools/improve/#example-usage)
-     - [**Advanced usage statistics**](https://www.codium.ai/contact/#/)
-     - [**Incorporating companies' best practices**](https://pr-agent-docs.codium.ai/tools/improve/#best-practices)
-     - [**SOC2 compliance check**](https://pr-agent-docs.codium.ai/tools/review/#configuration-options)
-     - [**Custom labels**](https://pr-agent-docs.codium.ai/tools/describe/#handle-custom-labels-from-the-repos-labels-page)
-     - [**Inline file summary**](https://pr-agent-docs.codium.ai/tools/describe/#inline-file-summary)
-     - More ...
-
-6. **Supporting self-hosted git servers** - PR-Agent Pro can be installed on GitHub Enterprise Server, GitLab, and BitBucket. For more information, see the [installation guide](https://pr-agent-docs.codium.ai/installation/pr_agent_pro/).
+4. **Supporting self-hosted git servers** - PR-Agent Pro can be installed on GitHub Enterprise Server, GitLab, and BitBucket. For more information, see the [installation guide](https://pr-agent-docs.codium.ai/installation/pr_agent_pro/).
+
+**Additional features:**
+
+| Feature                                                                                                              | Description                                                                                                                                                       |
+|----------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [**Model selection**](https://pr-agent-docs.codium.ai/usage-guide/PR_agent_pro_models/#pr-agent-pro-models)          | Choose the model that best fits your needs, among top models like `GPT4` and `Claude-Sonnet-3.5`                                                                  
+| [**Global and wiki configuration**](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/)              | Control configurations for many repositories from a single location; <br>Edit configuration of a single repo without commiting code                               |
+| [**Apply suggestions**](https://pr-agent-docs.codium.ai/tools/improve/#overview)                                     | Generate commitable code from the relevant suggestions interactively by clicking on a checkbox                                                                    |
+| [**Suggestions impact**](https://pr-agent-docs.codium.ai/tools/improve/#assessing-impact-💎)                         | Automatically mark with ✅ suggestions that were implemented by the user (either directly in GitHub, or indirectly in the IDE)                                     |
+| [**Advanced usage statistics**](https://www.codium.ai/contact/#/)                                                    | PR-Agent Pro offers detailed statistics at user, repository, and company levels, including metrics about PR-Agent usage, and also general statistics and insights |
+| [**Incorporating companies' best practices**](https://pr-agent-docs.codium.ai/tools/improve/#best-practices)         | Use the companies' best practices as reference to increase the effectiveness and the relevance of the code suggestions                                            |
+| [**Interactive triggering**](https://pr-agent-docs.codium.ai/tools/analyze/#example-usage)                           | Interactively apply different tools via the `analyze` command                                                                                                     |
+| [**SOC2 compliance check**](https://pr-agent-docs.codium.ai/tools/review/#configuration-options)                     | Ensures the PR contains a ticket to a project management system (e.g., Jira, Asana, Trello, etc.)                                                                 
+| [**Custom labels**](https://pr-agent-docs.codium.ai/tools/describe/#handle-custom-labels-from-the-repos-labels-page) | Define custom labels for PR-Agent to assign to the PR                                                                                                             |
+
+**Additional tools:**
+
+- [**Custom Prompt Suggestions**](https://pr-agent-docs.codium.ai/tools/custom_prompt/)
+- [**Tests**](https://pr-agent-docs.codium.ai/tools/test/)
+- [**PR documentation**](https://pr-agent-docs.codium.ai/tools/documentation/)
+- [**Improve Component**](https://pr-agent-docs.codium.ai/tools/improve_component/)
+- [**Similar code search**](https://pr-agent-docs.codium.ai/tools/similar_code/)
+- [**CI feedback**](https://pr-agent-docs.codium.ai/tools/ci_feedback/)
+- [**Analyze PR components**](https://pr-agent-docs.codium.ai/tools/analyze/)
+
+
diff --git a/docs/docs/tools/improve.md b/docs/docs/tools/improve.md
@@ -1,33 +1,38 @@
 ## Overview
-The `improve` tool scans the PR code changes, and automatically generates suggestions for improving the PR code.
+The `improve` tool scans the PR code changes, and automatically generates [meaningful](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/pr_code_suggestions_prompts.toml#L41) suggestions for improving the PR code.
 The tool can be triggered automatically every time a new PR is [opened](../usage-guide/automations_and_usage.md#github-app-automatic-tools-when-a-new-pr-is-opened), or it can be invoked manually by commenting on any PR:
 ```
 /improve
 ```
 
+![code_suggestions_as_comment_closed.png](https://codium.ai/images/pr_agent/code_suggestions_as_comment_closed.png){width=512}
+
+![code_suggestions_as_comment_open.png](https://codium.ai/images/pr_agent/code_suggestions_as_comment_open.png){width=512}
+
+Note that the `Apply this suggestion` checkbox, which converts a suggestion into a commitable code comment, is available only for PR-Agent Pro 💎 users.
+
+
 ## Example usage
 
 ### Manual triggering
 
 Invoke the tool manually by commenting `/improve` on any PR. The code suggestions by default are presented as a single comment:
 
-![code suggestions as comment](https://codium.ai/images/pr_agent/code_suggestions_as_comment.png){width=512}
-
 To edit [configurations](#configuration-options) related to the improve tool, use the following template:
 ```
 /improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...
 ```
 
-For example, you can choose to present the suggestions as commitable code comments, by running the following command:
+For example, you can choose to present all the suggestions as commitable code comments, by running the following command:
 ```
 /improve --pr_code_suggestions.commitable_code_suggestions=true
 ```
 
 ![improve](https://codium.ai/images/pr_agent/improve.png){width=512}
 
 
-Note that a single comment has a significantly smaller PR footprint. We recommend this mode for most cases.
-Also note that collapsible are not supported in _Bitbucket_. Hence, the suggestions are presented there as code comments.
+As can be seen, a single table comment has a significantly smaller PR footprint. We recommend this mode for most cases.
+Also note that collapsible are not supported in _Bitbucket_. Hence, the suggestions can only be presented in Bitbucket as code comments.
 
 ### Automatic triggering
 
@@ -47,6 +52,22 @@ num_code_suggestions_per_chunk = ...
 - The `pr_commands` lists commands that will be executed automatically when a PR is opened.
 - The `[pr_code_suggestions]` section contains the configurations for the `improve` tool you want to edit (if any)
 
+### Assessing Impact 💎
+
+Note that PR-Agent pro tracks two types of implementations:
+
+- Direct implementation - when the user directly applies the suggestion by clicking the `Apply` checkbox.
+- Indirect implementation - when the user implements the suggestion in their IDE environment. In this case, PR-Agent will utilize, after each commit, a dedicated logic to identify if a suggestion was implemented, and will mark it as implemented.
+
+![code_suggestions_asses_impact](https://codium.ai/images/pr_agent/code_suggestions_asses_impact.png){width=512}
+
+In post-process, PR-Agent counts the number of suggestions that were implemented, and provides general statistics and insights about the suggestions' impact on the PR process.
+
+![code_suggestions_asses_impact_stats_1](https://codium.ai/images/pr_agent/code_suggestions_asses_impact_stats_1.png.png){width=384}
+
+![code_suggestions_asses_impact_stats_2](https://codium.ai/images/pr_agent/code_suggestions_asses_impact_stats_2.png.png){width=384}
+
+
 ## Usage Tips
 
 ### Self-review