- Documentation

- Better error handling in case could not deduce repo url

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.

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'

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 \\<QUESTION\\>**: Ask a question about the PR.   \n" \
                 "> - **/update_changelog**: Update the changelog based on the PR's contents.   \n" \
+                "> - **/help_docs \\<QUESTION\\>**: 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

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'.

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 += "<hr>\n\n<details> <summary><strong>💡 Tool usage guide:</strong></summary><hr> \n\n"
+                answer_str += HelpMessage.get_help_docs_usage_guide()
+                answer_str += "\n</details>\n"
+
             if get_settings().config.publish_output:
                 self.git_provider.publish_comment(answer_str)
             else:

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 <!-- /review -->")
                 checkbox_list.append(" - [ ] Run <!-- /improve -->")
                 checkbox_list.append(" - [ ] Run <!-- /update_changelog -->")
+                checkbox_list.append(" - [ ] Run <!-- /help_docs -->")
                 checkbox_list.append(" - [ ] Run <!-- /add_docs -->")
                 checkbox_list.append(" - [ ] Run <!-- /test -->")
                 checkbox_list.append(" - [ ] Run <!-- /improve_component -->")