From 736c8a695306830bdcff445d07ba901960e060d9 Mon Sep 17 00:00:00 2001 From: Almog Lavi Date: Tue, 26 Mar 2024 23:00:57 +0200 Subject: [PATCH] Refactor markdown image syntax and enhance documentation presentation --- .github/workflows/docs-ci.yaml | 1 + docs/docs/core-abilities/index.md | 2 +- docs/docs/css/custom.css | 9 ++ docs/docs/index.md | 90 ++++--------------- docs/docs/installation/pr_agent_pro.md | 16 ++-- docs/docs/tools/analyze.md | 12 ++- docs/docs/tools/ask.md | 6 +- docs/docs/tools/ci_feedback.md | 9 +- docs/docs/tools/custom_labels.md | 7 +- docs/docs/tools/custom_suggestions.md | 7 +- docs/docs/tools/describe.md | 49 ++-------- docs/docs/tools/documentation.md | 6 +- docs/docs/tools/improve.md | 14 +-- docs/docs/tools/review.md | 36 ++------ docs/docs/tools/similar_code.md | 12 +-- docs/docs/tools/similar_issues.md | 6 +- docs/docs/tools/test.md | 6 +- docs/docs/tools/update_changelog.md | 5 +- .../docs/usage-guide/configuration_options.md | 2 +- docs/docs/usage-guide/mail_notifications.md | 4 +- docs/mkdocs.yml | 2 + 21 files changed, 96 insertions(+), 205 deletions(-) diff --git a/.github/workflows/docs-ci.yaml b/.github/workflows/docs-ci.yaml index 1648fd44..b260039e 100644 --- a/.github/workflows/docs-ci.yaml +++ b/.github/workflows/docs-ci.yaml @@ -29,4 +29,5 @@ jobs: mkdocs-material- - run: pip install mkdocs-material - run: pip install "mkdocs-material[imaging]" + - run: pip install mkdocs-glightbox - run: mkdocs gh-deploy -f docs/mkdocs.yml --force diff --git a/docs/docs/core-abilities/index.md b/docs/docs/core-abilities/index.md index 074d4c09..0a97aaf3 100644 --- a/docs/docs/core-abilities/index.md +++ b/docs/docs/core-abilities/index.md @@ -43,7 +43,7 @@ We use [tiktoken](https://github.com/openai/tiktoken) to tokenize the patches af #### Example - +![Core Abilities](https://codium.ai/images/git_patch_logic.png){width=768} ## YAML Prompting TBD diff --git a/docs/docs/css/custom.css b/docs/docs/css/custom.css index 2f963ccd..e79736b4 100644 --- a/docs/docs/css/custom.css +++ b/docs/docs/css/custom.css @@ -16,3 +16,12 @@ font-size: 20px; margin-left: 0px !important; } + +.md-content img { + border-width: 1px; + border-style: solid; + border-color: black; + outline-width: 3px; + outline-style: solid; + outline-color: darkgray; + } \ No newline at end of file diff --git a/docs/docs/index.md b/docs/docs/index.md index ed02e502..246680df 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -47,83 +47,25 @@ PR-Agent offers extensive pull request functionalities across various git provid ## Example results -
-

/describe

-
-

- -

-
-
+#### [/describe](https://github.com/Codium-ai/pr-agent/pull/530) +
+![/describe](https://www.codium.ai/images/pr_agent/describe_new_short_main.png){width=512} +
-

/review

-
-

- - - -

-
-
+#### [/review](https://github.com/Codium-ai/pr-agent/pull/732#issuecomment-1975099151) +
+![/review](https://www.codium.ai/images/pr_agent/review_new_short_main.png){width=512} +
-

/improve

-
-

- - - -

-
-
- -

/generate_labels

-
-

- -

-
- -[//]: # (

/reflect_and_review:

) - -[//]: # (
) - -[//]: # (

) - -[//]: # () - -[//]: # (

) - -[//]: # (
) - -[//]: # (

/ask:

) - -[//]: # (
) - -[//]: # (

) - -[//]: # () - -[//]: # (

) - -[//]: # (
) - -[//]: # (

/improve:

) - -[//]: # (
) - -[//]: # (

) - -[//]: # () - -[//]: # (

) - -[//]: # (
) -
- - -
-
+#### [/improve](https://github.com/Codium-ai/pr-agent/pull/732#issuecomment-1975099159) +
+![/improve](https://www.codium.ai/images/pr_agent/improve_new_short_main.png){width=512} +
+#### [/generate_labels](https://github.com/Codium-ai/pr-agent/pull/530) +
+![/generate_labels](https://www.codium.ai/images/pr_agent/geneare_custom_labels_main_short.png){width=300} +
## How it works diff --git a/docs/docs/installation/pr_agent_pro.md b/docs/docs/installation/pr_agent_pro.md index cb371df7..bf3f32de 100644 --- a/docs/docs/installation/pr_agent_pro.md +++ b/docs/docs/installation/pr_agent_pro.md @@ -7,9 +7,7 @@ See [here](https://pr-agent-docs.codium.ai/#pr-agent-pro) for more details about Interested parties can subscribe to PR-Agent Pro through the following [link](https://www.codium.ai/pricing/). After subscribing, you are granted the ability to easily install the application across any of your repositories. - - - +![PR Agent Pro](https://codium.ai/images/pr_agent/pr_agent_pro_install.png){width=468} Each user who wants to use PR-Agent pro needs to buy a seat. Initially, CodiumAI offers a two-week trial period at no cost, after which continued access requires each user to secure a personal seat. @@ -27,7 +25,9 @@ Since GitLab platform does not support apps, installing PR-Agent Pro for GitLab Acquire a personal, project or group level access token. Enable the “api” scope in order to allow PR-Agent to read pull requests, comment and respond to requests. - +
+![Step 1](https://www.codium.ai/images/pr_agent/gitlab_pro_pat.png){width=750} +
Store the token in a safe place, you won’t be able to access it again after it was generated. @@ -42,7 +42,9 @@ You should see "Success!" displayed above the Submit button, and a shared secret Install a webhook for your repository or groups, by clicking “webhooks” on the settings menu. Click the “Add new webhook” button. - +
+![Step 3.1](https://www.codium.ai/images/pr_agent/gitlab_pro_add_webhook.png) +
In the webhook definition form, fill in the following fields: URL: https://pro.gitlab.pr-agent.codium.ai/webhook @@ -51,7 +53,9 @@ Secret token: Your CodiumAI key Trigger: Check the ‘comments’ and ‘merge request events’ boxes. Enable SSL verification: Check the box. - +
+![Step 3.2](https://www.codium.ai/images/pr_agent/gitlab_pro_webhooks.png){width=750} +
### Step 4 diff --git a/docs/docs/tools/analyze.md b/docs/docs/tools/analyze.md index 1264be7f..3b7c6d58 100644 --- a/docs/docs/tools/analyze.md +++ b/docs/docs/tools/analyze.md @@ -11,13 +11,11 @@ It can be invoked manually by commenting on any PR: ## Example usage An example [result](https://github.com/Codium-ai/pr-agent/pull/546#issuecomment-1868524805): - - - - - - - +![Analyze 1](https://codium.ai/images/pr_agent/analyze_1.png){width=750} +→ +![Analyze 2](https://codium.ai/images/pr_agent/analyze_2.png){width=750} +→ +![Analyze 3](https://codium.ai/images/pr_agent/analyze_3.png){width=750} **Notes** diff --git a/docs/docs/tools/ask.md b/docs/docs/tools/ask.md index e6e02160..453807fd 100644 --- a/docs/docs/tools/ask.md +++ b/docs/docs/tools/ask.md @@ -7,9 +7,9 @@ It can be invoked manually by commenting on any PR: ``` For example: - +![Ask Comment](https://codium.ai/images/pr_agent/ask_comment.png){width=768} - +![Ask](https://codium.ai/images/pr_agent/ask.png){width=768} ## Ask lines @@ -18,6 +18,6 @@ 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. - +![Ask Line](https://codium.ai/images/pr_agent/Ask_line.png){width=768} Note that the tool does not have "memory" of previous questions, and answers each question independently. diff --git a/docs/docs/tools/ci_feedback.md b/docs/docs/tools/ci_feedback.md index 2949f138..998fef56 100644 --- a/docs/docs/tools/ci_feedback.md +++ b/docs/docs/tools/ci_feedback.md @@ -8,13 +8,10 @@ The tool analyzes the failed checks and provides several feedbacks: - Failure summary - Relevant error logs - - - +![Failed Check 1](https://www.codium.ai/images/pr_agent/failed_check1.png){width=768} + → - - - +![Failed Check 2](https://www.codium.ai/images/pr_agent/failed_check2.png){width=768} ___ diff --git a/docs/docs/tools/custom_labels.md b/docs/docs/tools/custom_labels.md index d8dbb1a1..29f1a9e2 100644 --- a/docs/docs/tools/custom_labels.md +++ b/docs/docs/tools/custom_labels.md @@ -9,11 +9,11 @@ For example: If we wish to add detect changes to SQL queries in a given PR, we can add the following custom label along with its description: - +![Custom labels list](https://codium.ai/images/pr_agent/custom_labels_list.png){width=768} When running the `generate_labels` tool on a PR that includes changes in SQL queries, it will automatically suggest the custom label: - +![Custom labels published](https://codium.ai/images/pr_agent/custom_label_published.png){width=768} Note that in addition to the dedicated tool `generate_labels`, the custom labels will also be used by the `describe` tool. @@ -36,7 +36,8 @@ b. Add/edit the custom labels. It should be formatted as follows: * Label name: The name of the custom label. * Description: Start the description of with prefix `pr_agent:`, for example: `pr_agent: Description of when AI should suggest this label`.
The description should be comprehensive and detailed, indicating when to add the desired label. - + +![Add native custom labels](https://codium.ai/images/pr_agent/add_native_custom_labels.png){width=880} c. Now the custom labels will be included in the `generate_labels` tool. diff --git a/docs/docs/tools/custom_suggestions.md b/docs/docs/tools/custom_suggestions.md index 0b19ecef..85720c11 100644 --- a/docs/docs/tools/custom_suggestions.md +++ b/docs/docs/tools/custom_suggestions.md @@ -43,10 +43,9 @@ The instructions above are just an example. We want to emphasize that the prompt Results obtained with the prompt above: - - - - +![Custom suggestions prompt](https://codium.ai/images/pr_agent/custom_suggestions_prompt.png){width=512} +→ +![Custom suggestions results](https://codium.ai/images/pr_agent/custom_suggestions_result.png){width=768} ## Configuration options diff --git a/docs/docs/tools/describe.md b/docs/docs/tools/describe.md index cf7ccdfb..e0de5153 100644 --- a/docs/docs/tools/describe.md +++ b/docs/docs/tools/describe.md @@ -7,17 +7,9 @@ The tool can be triggered automatically every time a new PR is [opened](../usage ``` For example: - - - - - +![Describe comment](https://codium.ai/images/pr_agent/describe_comment.png){width=512} - - - - - +![Describe New](https://codium.ai/images/pr_agent/describe_new.png){width=512} @@ -57,29 +49,17 @@ This feature enables you to copy the `changes walkthrough` table to the "Files c To copy the `changes walkthrough` table to the "Files changed" tab, you can click on the checkbox that appears PR Description status message below the main PR Description: - - - - - +![Add table checkbox](https://codium.ai/images/pr_agent/add_table_checkbox.png){width=512} If you prefer to have the file summaries appear in the "Files changed" tab on every PR, change the `pr_description.inline_file_summary` parameter in the configuration file, possible values are: - `'table'`: File changes walkthrough table will be displayed on the top of the "Files changed" tab, in addition to the "Conversation" tab. - - - - - +![Diffview table](https://codium.ai/images/pr_agent/diffview-table.png){width=512} - `true`: A collapsable file comment with changes title and a changes summary for each file in the PR. - - - - - +![Diffview changes](https://codium.ai/images/pr_agent/diffview_changes.png){width=512} - `false` (`default`): File changes walkthrough will be added only to the "Conversation" tab. @@ -99,11 +79,7 @@ Now add/edit the custom labels. they should be formatted as follows: * Description: Start the description of with prefix `pr_agent:`, for example: `pr_agent: Description of when AI should suggest this label`.
The description should be comprehensive and detailed, indicating when to add the desired label. For example: - - - - - +![Add native custom labels](https://codium.ai/images/pr_agent/add_native_custom_labels.png){width=768} ### Markers template @@ -126,19 +102,12 @@ pr_agent:walkthrough ``` The marker `pr_agent: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. - - - - - +![Describe markers before](https://codium.ai/images/pr_agent/describe_markers_before.png){width=512} → - - - - - +![Describe markers after](https://codium.ai/images/pr_agent/describe_markers_after.png){width=512} + **Configuration params**: diff --git a/docs/docs/tools/documentation.md b/docs/docs/tools/documentation.md index b3fb0ba4..4318ee45 100644 --- a/docs/docs/tools/documentation.md +++ b/docs/docs/tools/documentation.md @@ -7,11 +7,11 @@ It can be invoked manually by commenting on any PR: ``` For example: - +![Docs command](https://codium.ai/images/pr_agent/docs_command.png){width=768} - +![Docs component](https://codium.ai/images/pr_agent/docs_components.png){width=768} - +![Docs single component](https://codium.ai/images/pr_agent/docs_single_component.png){width=768} ## Configuration options - `docs_style`: The exact style of the documentation (for python docstring). you can choose between: `google`, `numpy`, `sphinx`, `restructuredtext`, `plain`. Default is `sphinx`. diff --git a/docs/docs/tools/improve.md b/docs/docs/tools/improve.md index f5808139..40945775 100644 --- a/docs/docs/tools/improve.md +++ b/docs/docs/tools/improve.md @@ -9,20 +9,12 @@ The tool can be triggered automatically every time a new PR is [opened](../usage The code suggestions can be presented as a single comment (via `pr_code_suggestions.summarize=true`): - - - - - - +![code suggestions as comment](https://codium.ai/images/pr_agent/code_suggestions_as_comment.png){width=512} Or as a separate commitable code comment for each suggestion: - - - - - +![imporove](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. diff --git a/docs/docs/tools/review.md b/docs/docs/tools/review.md index a8bd5a66..32314b5c 100644 --- a/docs/docs/tools/review.md +++ b/docs/docs/tools/review.md @@ -6,17 +6,9 @@ The tool can be triggered automatically every time a new PR is [opened](../usage ``` For example: - - - - - +![review comment](https://codium.ai/images/pr_agent/review_comment.png){width=512} - - - - - +![review](https://codium.ai/images/pr_agent/review_comment.png){width=512} ## Configuration options @@ -70,11 +62,7 @@ For invoking the incremental mode, the following command can be used: ``` Note that the incremental mode is only available for GitHub. - - - - - +![incremental review](https://codium.ai/images/pr_agent/incremental_review_2.png){width=512} ### PR Reflection @@ -84,23 +72,11 @@ By invoking: ``` The tool will first ask the author questions about the PR, and will guide the review based on their answers. - - - - - +![reflection questions](https://codium.ai/images/pr_agent/reflection_questions.png){width=512} - - - - - +![reflection answers](https://codium.ai/images/pr_agent/reflection_answers.png){width=512} - - - - - +![reflection insights](https://codium.ai/images/pr_agent/reflection_insights.png){width=512} ## Usage Tips diff --git a/docs/docs/tools/similar_code.md b/docs/docs/tools/similar_code.md index a35111d7..5f2af5c8 100644 --- a/docs/docs/tools/similar_code.md +++ b/docs/docs/tools/similar_code.md @@ -5,7 +5,8 @@ For example: `Global Search` for a method called `chat_completion`: - +![similar code global](https://codium.ai/images/pr_agent/similar_code_global2.png){width=768} + PR-Agent will examine the code component and will extract the most relevant keywords to search for similar code: @@ -16,11 +17,12 @@ PR-Agent will examine the code component and will extract the most relevant keyw Search result link example: - +![code search result single](https://codium.ai/images/pr_agent/code_search_result_single.png){width=768} + `Organization Search`: - +![similar code org](https://codium.ai/images/pr_agent/similar_code_org.png){width=768} ## How to use @@ -47,11 +49,11 @@ It can be invoked automatically from the analyze table, can be accessed by: /analyze ``` Choose the components you want to find similar code for, and click on the `similar` checkbox. - +![analyze similar](https://codium.ai/images/pr_agent/analyze_similar.png){width=768} If you are looking to search for similar code in the organization's codebase, you can click on the `Organization` checkbox, and it will invoke a new search command just for the organization's codebase. - +![similar code global](https://codium.ai/images/pr_agent/similar_code_global.png){width=768} ## Configuration options diff --git a/docs/docs/tools/similar_issues.md b/docs/docs/tools/similar_issues.md index 3d492c0a..239b4e90 100644 --- a/docs/docs/tools/similar_issues.md +++ b/docs/docs/tools/similar_issues.md @@ -6,11 +6,11 @@ It can be invoked manually by commenting on any PR: ``` For example: - +![similar_issue_original_issue](https://codium.ai/images/pr_agent/similar_issue_original_issue.png){width=768} - +![similar_issue_comment](https://codium.ai/images/pr_agent/similar_issue_comment.png){width=768} - +![similar_issue](https://codium.ai/images/pr_agent/similar_issue.png){width=768} Note that to perform retrieval, the `similar_issue` tool indexes all the repo previous issues (once). diff --git a/docs/docs/tools/test.md b/docs/docs/tools/test.md index a45f6faf..6c1901b1 100644 --- a/docs/docs/tools/test.md +++ b/docs/docs/tools/test.md @@ -10,11 +10,11 @@ To get a list of the components that changed in the PR, use the [`analyze`](./an An example [result](https://github.com/Codium-ai/pr-agent/pull/598#issuecomment-1913679429): - +![test1](https://codium.ai/images/pr_agent/test1.png){width=704} - +![test2](https://codium.ai/images/pr_agent/test2.png){width=768} - +![test3](https://codium.ai/images/pr_agent/test3.png){width=768} **Notes** - Language that are currently supported by the tool: Python, Java, C++, JavaScript, TypeScript. diff --git a/docs/docs/tools/update_changelog.md b/docs/docs/tools/update_changelog.md index 4c423a3e..4f4de235 100644 --- a/docs/docs/tools/update_changelog.md +++ b/docs/docs/tools/update_changelog.md @@ -6,10 +6,9 @@ It can be invoked manually by commenting on any PR: ``` For example: - - - +![update_changelog_comment](https://codium.ai/images/pr_agent/update_changelog_comment.png){width=768} +![update_changelog](https://codium.ai/images/pr_agent/update_changelog.png){width=768} ## Configuration options diff --git a/docs/docs/usage-guide/configuration_options.md b/docs/docs/usage-guide/configuration_options.md index 9b15babb..1d56baa2 100644 --- a/docs/docs/usage-guide/configuration_options.md +++ b/docs/docs/usage-guide/configuration_options.md @@ -16,7 +16,7 @@ In terms of precedence, wiki configurations will override local configurations, Specifically for GitHub, with PR-Agent-Pro you can set configurations by creating a page called `.pr_agent.toml` in the [wiki](https://github.com/Codium-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**. - +![wiki_configuration](https://codium.ai/images/pr_agent/wiki_configuration.png){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, to allow better presentation when displayed in the wiki as markdown. An example content: diff --git a/docs/docs/usage-guide/mail_notifications.md b/docs/docs/usage-guide/mail_notifications.md index 1e5b2e8a..82dc10a0 100644 --- a/docs/docs/usage-guide/mail_notifications.md +++ b/docs/docs/usage-guide/mail_notifications.md @@ -2,8 +2,8 @@ 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: - +![notifications](https://codium.ai/images/pr_agent/notifications.png){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). - \ No newline at end of file +![filter_mail_notifications](https://codium.ai/images/pr_agent/filter_mail_notifications.png){width=512} diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c3e10abd..bcf39b36 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -77,6 +77,7 @@ theme: plugins: - social - search + - glightbox extra: generator: false @@ -112,6 +113,7 @@ markdown_extensions: - pymdownx.details - pymdownx.superfences - pymdownx.mark + - md_in_html - attr_list - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji