Improve help_docs documentation with clearer structure and usage examples

docs/docs/tools/help_docs.md

@@ -1,35 +1,46 @@
 ## Overview
 
-The `help_docs` tool answers a question based on a given relative path of documentation (which defaults to docs/), either from the repository of this merge request or from a given one.
+The `help_docs` tool can answer a free-text question based on a git documentation folder.
+
 It can be invoked manually by commenting on any PR or Issue:
 ```
 /help_docs "..."
 ```
+Or configured to be triggered automatically when a [new issue is opened](#run-as-a-github-action).
+
+The tool assumes by default that the documentation is located in the root of the repository, at `/docs` folder.
+However, this can be customized by setting the `docs_path` configuration option:
+
+```toml
+[pr_help_docs]
+repo_url = ""                 # The repository to use as context
+docs_path = "docs"            # The documentation folder
+repo_default_branch = "main"  # The branch to use in case repo_url overwritten
+
+```
+
+See more configuration options in the [Configuration options](#configuration-options) section.
 
 ## Example usage
-#### Asking a question about this repository:
-![help_docs on the documentation of this repository](https://codium.ai/images/pr_agent/help_docs_comment.png){width=512}
 
-#### Asking a question about another repository under branch: main:
+[//]: # (#### Asking a question about this repository:)
+
+[//]: # (![help_docs on the documentation of this repository](https://codium.ai/images/pr_agent/help_docs_comment.png){width=512})
+
+**Asking a question about another repository**
+
 ![help_docs on the documentation of another repository](https://codium.ai/images/pr_agent/help_docs_comment_explicit_git.png){width=512}
 
-#### Response for the first question: 
+**Response**:
+
 ![help_docs response](https://codium.ai/images/pr_agent/help_docs_response.png){width=512}
 
-## Configuration options
+## Run automatically when a new issue is opened
 
-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:
+You can configure PR-Agent to run `help_docs` automatically on any newly created issue.
+This can be useful, for example, for providing immediate feedback to users who open issues with questions on open-source projects with extensive documentation.
 
-- `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.
+Here's how:
-- `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.
-
----
-## Run as a GitHub Action
-
-You can use our pre-built Github Action Docker image to run help_docs on any newly created issue, as a Github Action. Here's how:
 
 1) Follow the steps depicted under [Run as a Github Action](https://qodo-merge-docs.qodo.ai/installation/github/#run-as-a-github-action) to create a new workflow, such as:`.github/workflows/help_docs.yml`:
 
@@ -76,10 +87,22 @@ jobs:
             export github__user_token=$GITHUB_TOKEN && \            
             export github__base_url=$GITHUB_API_URL && \
             export openai__key=$OPENAI_KEY && \
-            export config__verbosity_level=2 && \
+            python -m pr_agent.cli --issue_url=$ISSUE_URL --pr_help_docs.repo_url="..." --pr_help_docs.docs_path="..." --pr_help_docs.openai_key=$OPENAI_KEY && \help_docs \"$ISSUE_BODY\""
-            python -m pr_agent.cli --issue_url=$ISSUE_URL help_docs \"$ISSUE_BODY\""
 ```
 
-3) Following completion of the remaining steps (such as adding secrets and any env. variables), merge this change to your main branch.
+3) Following completion of the remaining steps (such as adding secrets and relevant configurations, such as `repo_url` and `docs_path`) merge this change to your main branch.
-When a new issue is opened, you should see a comment from `github-actions` bot with an auto response, assuming the question is a relevant one.
+When a new issue is opened, you should see a comment from `github-actions` bot with an auto response, assuming the question is related to the documentation of the repository.
+---
+
+
+## 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.
+
 ---