describe

README.md

@@ -17,7 +17,7 @@ Making pull requests less painful with an AI agent
 
 CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull requests faster and more efficiently. It automatically analyzes the pull request and can provide several types of commands:
 
-‣ **Auto Description (`/describe`)**: Automatically generating [PR description](https://github.com/Codium-ai/pr-agent/pull/229#issue-1860711415) - title, type, summary, code walkthrough and labels.
+‣ **Auto Description (`/describe`)**: Automatically generating [PR description](./docs/DESCRIBE.md) - title, type, summary, code walkthrough and labels.
 \
 ‣ **Auto Review (`/review`)**: [Adjustable feedback](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695022908) about the PR main theme, type, relevant tests, security issues, score, and various suggestions for the PR content.
 \

docs/DESCRIBE.md

@@ -0,0 +1,50 @@
+## Describe
+
+The `describe` tool scans the PR code changes, and automatically generates PR description - title, type, summary, code walkthrough and labels.
+It can ba invoked manually by commenting on any PR:
+```
+/describe
+```
+
+
+<img src=./../pics/describe_comment.png width="768">
+
+<img src=./../pics/describe.png width="768">
+
+The `describe` tool can also be triggered automatically every time a new PR is opened. See examples for automatic triggers for [GitHub App](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) and [GitHub Action](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#working-with-github-action)
+
+### Configuration options
+
+Under the section 'pr_description', the [configuration file](pr_agent/settings/configuration.toml) contains options to customize the 'describe' tool:
+
+- `publish_labels`: if set to true, the tool will publish the labels to the PR. Default is true.
+
+- `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 origianl description. Default is false.
+
+- `add_original_user_description`: if set to true, the tool will add the original user description to the generated description. Default is false.
+
+- `add_original_user_title`: if set to true, the tool will keep the original PR title, and won't change it. Default is false.
+
+- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".
+
+#### Markers template
+
+markers template enable to easily integrate user's content and auto-generated content.
+
+- `use_description_markers`: if set to true, the tool will use markers template. It replaces every marker of the form `pr_agent:marker_name` with the relevant content. Default is false.
+For example, if the PR original description was:
+```
+User content...
+
+## PR Type:
+pr_agent:pr_type
+
+## PR Description:
+pr_agent:summary
+
+## PR Walkthrough:
+pr_agent:walkthrough
+```
+The marker `pr_agent:pr_type` will be replaced with the PR type, `pr_agent:summary` will be replaced with the PR summary, and `pr_agent:walkthrough` will be replaced with the PR walkthrough.
+
+- `include_generated_by_header`: if set to true, the tool will add a dedicated header: 'Generated by PR Agent at ...' to any automatic content. Default is true.