docs: improve formatting and readability of documentation

docs/docs/tools/analyze.md

@@ -14,6 +14,5 @@ An example result:
 
 ![Analyze 1](https://codium.ai/images/pr_agent/analyze_1.png){width=750}
 
-**Notes**
-
-- Language that are currently supported: Python, Java, C++, JavaScript, TypeScript, C#.
+!!! note "Language that are currently supported:"
+    Python, Java, C++, JavaScript, TypeScript, C#.

docs/docs/tools/ask.md

@@ -38,20 +38,20 @@ where `https://real_link_to_image` is the direct link to the image.
 Note that GitHub has a built-in mechanism of pasting images in comments. However, pasted image does not provide a direct link.
 To get a direct link to an image, we recommend using the following scheme:
 
-1) First, post a comment that contains **only** the image:
+1\. First, post a comment that contains **only** the image:
 
 ![Ask image1](https://codium.ai/images/pr_agent/ask_images1.png){width=512}
 
-2) Quote reply to that comment:
+2\. Quote reply to that comment:
 
 ![Ask image2](https://codium.ai/images/pr_agent/ask_images2.png){width=512}
 
-3) In the screen opened, type the question below the image:
+3\. In the screen opened, type the question below the image:
 
 ![Ask image3](https://codium.ai/images/pr_agent/ask_images3.png){width=512}
 ![Ask image4](https://codium.ai/images/pr_agent/ask_images4.png){width=512}
 
-4) Post the comment, and receive the answer:
+4\. Post the comment, and receive the answer:
 
 ![Ask image5](https://codium.ai/images/pr_agent/ask_images5.png){width=512}
 

docs/docs/tools/custom_prompt.md

@@ -51,8 +51,8 @@ Results obtained with the prompt above:
 
 ## Configuration options
 
-`prompt`: the prompt for the tool. It should be a multi-line string.
+- `prompt`: the prompt for the tool. It should be a multi-line string.
 
-`num_code_suggestions_per_chunk`: number of code suggestions provided by the 'custom_prompt' tool, per chunk. Default is 4.
+- `num_code_suggestions_per_chunk`: number of code suggestions provided by the 'custom_prompt' tool, per chunk. Default is 4.
 
-`enable_help_text`: if set to true, the tool will display a help text in the comment. Default is true.
+- `enable_help_text`: if set to true, the tool will display a help text in the comment. Default is true.

docs/docs/tools/describe.md

@@ -143,7 +143,7 @@ The marker `pr_agent:type` will be replaced with the PR type, `pr_agent:summary`
 
 ![Describe markers before](https://codium.ai/images/pr_agent/describe_markers_before.png){width=512}
 
-→
+becomes
 
 ![Describe markers after](https://codium.ai/images/pr_agent/describe_markers_after.png){width=512}
 

docs/docs/tools/documentation.md

@@ -27,7 +27,6 @@ You can state a name of a specific component in the PR to get documentation only
  - `docs_style`: The exact style of the documentation (for python docstring). you can choose between: `google`, `numpy`, `sphinx`, `restructuredtext`, `plain`. Default is `sphinx`.
  - `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".
 
-**Notes**
-
-- Language that are currently fully supported: Python, Java, C++, JavaScript, TypeScript, C#.
-- This tool can also be triggered interactively by using the [`analyze`](./analyze.md) tool.
+!!! notes "Notes"
+    - The following languages are currently supported: Python, Java, C++, JavaScript, TypeScript, C#.
+    - This tool can also be triggered interactively by using the [`analyze`](./analyze.md) tool.

docs/docs/tools/implement.md

@@ -10,8 +10,9 @@ It leverages LLM technology to transform PR comments and review suggestions into
 
 ### For Reviewers
 
-Reviewers can request code changes by: <br>
-1. Selecting the code block to be modified. <br>
+Reviewers can request code changes by:
+
+1. Selecting the code block to be modified.
 2. Adding a comment with the syntax: 
 ```
 /implement <code-change-description>
@@ -46,7 +47,8 @@ You can reference and implement changes from any comment by:
 Note that the implementation will occur within the review discussion thread.
 
 
-**Configuration options** <br>
+**Configuration options**
+
 - Use `/implement` to implement code change within and based on the review discussion. <br>
 - Use `/implement <code-change-description>` inside a review discussion to implement specific instructions. <br>
 - Use `/implement <link-to-review-comment>` to indirectly call the tool from any comment. <br>

docs/docs/tools/improve.md

@@ -9,9 +9,9 @@ The tool can be triggered automatically every time a new PR is [opened](../usage
 
 ![code_suggestions_as_comment_open.png](https://codium.ai/images/pr_agent/code_suggestions_as_comment_open.png){width=512}
 
-Note that the following features are available only for Qodo Merge💎 users:
-- The `Apply this suggestion` checkbox, which interactively converts a suggestion into a committable code comment
-- The `More` checkbox to generate additional suggestions
+!!! note "The following features are available only for Qodo Merge 💎 users:"
+    - The `Apply this suggestion` checkbox, which interactively converts a suggestion into a committable code comment
+    - The `More` checkbox to generate additional suggestions
 
 ## Example usage
 
@@ -196,7 +196,7 @@ And the label will be: `{organization_name} best practice`.
 
 >`Platforms supported: GitHub`
 
-'Auto best practices' is a novel Qodo Merge capability that:
+`Auto best practices` is a novel Qodo Merge capability that:
 
 1. Identifies recurring patterns from accepted suggestions
 2. **Automatically** generates [best practices page](https://github.com/qodo-ai/pr-agent/wiki/.pr_agent_auto_best_practices) based on what your team consistently values
@@ -315,17 +315,13 @@ code_suggestions_self_review_text = "... (your text here) ..."
 ### How many code suggestions are generated?
 Qodo Merge uses a dynamic strategy to generate code suggestions based on the size of the pull request (PR). Here's how it works:
 
-1) Chunking large PRs:
-
+#### 1. Chunking large PRs
 - Qodo Merge divides large PRs into 'chunks'.
 - Each chunk contains up to `pr_code_suggestions.max_context_tokens` tokens (default: 14,000).
 
-
-2) Generating suggestions:
-
+#### 2. Generating suggestions
 - For each chunk, Qodo Merge generates up to `pr_code_suggestions.num_code_suggestions_per_chunk` suggestions (default: 4).
 
-
 This approach has two main benefits:
 
 - Scalability: The number of suggestions scales with the PR size, rather than being fixed.

docs/docs/tools/improve_component.md

@@ -18,9 +18,9 @@ The tool will generate code suggestions for the selected component (if no compon
 
 ![improve_component2](https://codium.ai/images/pr_agent/improve_component2.png){width=768}
 
-**Notes**
-- Language that are currently supported by the tool: Python, Java, C++, JavaScript, TypeScript, C#.
-- This tool can also be triggered interactively by using the [`analyze`](./analyze.md) tool.
+!!! note "Notes"
+    - Language that are currently supported by the tool: Python, Java, C++, JavaScript, TypeScript, C#.
+    - This tool can also be triggered interactively by using the [`analyze`](./analyze.md) tool.
 
 ## Configuration options
 - `num_code_suggestions`: number of code suggestions to provide. Default is 4

docs/docs/tools/similar_issues.md

@@ -16,14 +16,17 @@ It can be invoked manually by commenting on any PR:
 
 Note that to perform retrieval, the `similar_issue` tool indexes all the repo previous issues (once).
 
+### Selecting a Vector Database
+Configure your preferred database by changing the `pr_similar_issue` parameter in `configuration.toml` file.
 
-**Select VectorDBs** by changing `pr_similar_issue` parameter in `configuration.toml` file
+#### Available Options
+Choose from the following Vector Databases:
 
-2 VectorDBs are available to switch in
 1. LanceDB
 2. Pinecone
 
-To enable usage of the '**similar issue**' tool for Pinecone, you need to set the following keys in `.secrets.toml` (or in the relevant environment variables):
+#### Pinecone Configuration
+To use Pinecone with the `similar issue` tool, add these credentials to `.secrets.toml` (or set as environment variables):
 
 ```
 [pinecone]

docs/docs/tools/test.md

@@ -17,9 +17,9 @@ The tool will generate tests for the selected component (if no component is stat
 
 (Example taken from [here](https://github.com/Codium-ai/pr-agent/pull/598#issuecomment-1913679429)):
 
-**Notes** <br>
-- The following languages are currently supported: Python, Java, C++, JavaScript, TypeScript, C#. <br>
-- This tool can also be triggered interactively by using the [`analyze`](./analyze.md) tool.
+!!! notes "Notes"
+    - The following languages are currently supported: Python, Java, C++, JavaScript, TypeScript, C#.
+    - This tool can also be triggered interactively by using the [`analyze`](./analyze.md) tool.
 
 
 ## Configuration options