diff --git a/docs/docs/tools/help_docs.md b/docs/docs/tools/help_docs.md new file mode 100644 index 00000000..70a59ff9 --- /dev/null +++ b/docs/docs/tools/help_docs.md @@ -0,0 +1,25 @@ +## Overview + +The `help_docs` tool answers a question based on a given relative path of documentation, either from the repository of this merge request or from a given one. +It can be invoked manually by commenting on any PR: +``` +/help_docs "..." +``` + +## Example usage + +![TODO help_docs on the documentation of this repository](https://codium.ai/images/pr_agent/help_docs_comment.png){width=512} + +![TODO help_docs on the documentation of another repository](https://codium.ai/images/pr_agent/help_docs_comment_implicit_git.png){width=512} + +![TODO help_docs](https://codium.ai/images/pr_agent/help_docs_result.png){width=512} + +## Configuration options + +Under the section `--pr_help_docs`, the [configuration file](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L50) contains options to customize the 'help docs' tool: + +- `repo_url`: If not overwritten, will use the repo from where the context came from (issue or PR), otherwise - use the given repo as context. +- `repo_default_branch`: The branch to use in case repo_url overwritten, otherwise - has no effect. +- `docs_path`: Relative path from root of repository (either the one this PR has been issued for, or above repo url). +- `exclude_root_readme`: Whether or not to exclude the root README file for querying the model. +- `supported_doc_exts` : Which file extensions should be included for the purpose of querying the model. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c14773b3..86a8b07d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -28,6 +28,7 @@ nav: - Improve: 'tools/improve.md' - Ask: 'tools/ask.md' - Update Changelog: 'tools/update_changelog.md' + - Help Docs: 'tools/help_docs.md' - Help: 'tools/help.md' - 💎 Analyze: 'tools/analyze.md' - 💎 Test: 'tools/test.md' diff --git a/pr_agent/servers/help.py b/pr_agent/servers/help.py index 7edd13db..e3cdf0de 100644 --- a/pr_agent/servers/help.py +++ b/pr_agent/servers/help.py @@ -6,6 +6,7 @@ class HelpMessage: "> - **/improve [--extended]**: Suggest code improvements. Extended mode provides a higher quality feedback. \n" \ "> - **/ask \\**: Ask a question about the PR. \n" \ "> - **/update_changelog**: Update the changelog based on the PR's contents. \n" \ + "> - **/help_docs \\**: Given a path to documentation (either for this repository or for a given one), ask a question. \n" \ "> - **/add_docs** 💎: Generate docstring for new components introduced in the PR. \n" \ "> - **/generate_labels** 💎: Generate labels for the PR based on the PR's contents. \n" \ "> - **/analyze** 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. \n\n" \ @@ -201,3 +202,17 @@ some_config2=... output += f"\n\nSee the improve [usage page](https://pr-agent-docs.codium.ai/tools/improve/) for a comprehensive guide on using this tool.\n\n" return output + + + @staticmethod + def get_help_docs_usage_guide(): + output = "**Overview:**\n" + output += """\ +The help docs tool, named `help_docs`, answers a question based on a given relative path of documentation, either from the repository of this merge request or from a given one." +It can be invoked manually by commenting on any PR: +``` +/help_docs "..." +``` +""" + output += f"\n\nSee the [help_docs usage](https://pr-agent-docs.codium.ai/tools/help_docs/) page for a comprehensive guide on using this tool.\n\n" + return output diff --git a/pr_agent/settings/configuration.toml b/pr_agent/settings/configuration.toml index 899e9c1f..79025467 100644 --- a/pr_agent/settings/configuration.toml +++ b/pr_agent/settings/configuration.toml @@ -218,6 +218,7 @@ repo_default_branch = "main" docs_path = "docs" exclude_root_readme = false supported_doc_exts = [".md", ".mdx", ".rst"] +enable_help_text=false [github] # The type of deployment to create. Valid values are 'app' or 'user'. diff --git a/pr_agent/tools/pr_help_docs.py b/pr_agent/tools/pr_help_docs.py index d8dbcc66..5695065a 100644 --- a/pr_agent/tools/pr_help_docs.py +++ b/pr_agent/tools/pr_help_docs.py @@ -16,6 +16,7 @@ from pr_agent.algo.utils import clip_tokens, get_max_tokens, load_yaml, ModelTyp from pr_agent.config_loader import get_settings from pr_agent.git_providers import get_git_provider_with_context from pr_agent.log import get_logger +from pr_agent.servers.help import HelpMessage #Common code that can be called from similar tools: @@ -221,6 +222,8 @@ class PRHelpDocs(object): get_logger().debug(f"No explicit repo url provided, deducing it from type: {self.git_provider.__class__.__name__} " f"context url: {self.ctx_url}") self.repo_url = self.git_provider.get_git_repo_url(self.ctx_url) + if not self.repo_url: + raise Exception(f"Unable to deduce repo url from type: {self.git_provider.__class__.__name__} url: {self.ctx_url}") get_logger().debug(f"deduced repo url: {self.repo_url}") self.repo_desired_branch = None #Inferred from the repo provider. @@ -334,6 +337,12 @@ class PRHelpDocs(object): if not answer_str or int(response_yaml.get('question_is_relevant', '1')) == 0: get_logger().info(f"No answer found") return "" + + if self.git_provider.is_supported("gfm_markdown") and get_settings().pr_help_docs.enable_help_text: + answer_str += "
\n\n
💡 Tool usage guide:
\n\n" + answer_str += HelpMessage.get_help_docs_usage_guide() + answer_str += "\n
\n" + if get_settings().config.publish_output: self.git_provider.publish_comment(answer_str) else: diff --git a/pr_agent/tools/pr_help_message.py b/pr_agent/tools/pr_help_message.py index 9ff5d6e3..f7ff9948 100644 --- a/pr_agent/tools/pr_help_message.py +++ b/pr_agent/tools/pr_help_message.py @@ -208,6 +208,7 @@ class PRHelpMessage: tool_names.append(f"[REVIEW]({base_path}/review/)") tool_names.append(f"[IMPROVE]({base_path}/improve/)") tool_names.append(f"[UPDATE CHANGELOG]({base_path}/update_changelog/)") + tool_names.append(f"[HELP DOCS]({base_path}/help_docs/)") tool_names.append(f"[ADD DOCS]({base_path}/documentation/) 💎") tool_names.append(f"[TEST]({base_path}/test/) 💎") tool_names.append(f"[IMPROVE COMPONENT]({base_path}/improve_component/) 💎") @@ -223,6 +224,7 @@ class PRHelpMessage: descriptions.append("Adjustable feedback about the PR, possible issues, security concerns, review effort and more") descriptions.append("Code suggestions for improving the PR") descriptions.append("Automatically updates the changelog") + descriptions.append("Answers a question regarding this repository, or a given one, based on given documentation path") descriptions.append("Generates documentation to methods/functions/classes that changed in the PR") descriptions.append("Generates unit tests for a specific component, based on the PR code change") descriptions.append("Code suggestions for a specific component that changed in the PR") @@ -239,6 +241,7 @@ class PRHelpMessage: commands.append("`/review`") commands.append("`/improve`") commands.append("`/update_changelog`") + commands.append("`/help_docs`") commands.append("`/add_docs`") commands.append("`/test`") commands.append("`/improve_component`") @@ -254,6 +257,7 @@ class PRHelpMessage: checkbox_list.append(" - [ ] Run ") checkbox_list.append(" - [ ] Run ") checkbox_list.append(" - [ ] Run ") + checkbox_list.append(" - [ ] Run ") checkbox_list.append(" - [ ] Run ") checkbox_list.append(" - [ ] Run ") checkbox_list.append(" - [ ] Run ")