Improve documentation formatting and readability

[ofir-frd]

PR Type

Documentation

---

Description

• Improved formatting and readability across multiple documentation files.

• Standardized note formatting using !!! note syntax.

• Enhanced clarity in configuration instructions and examples.

• Corrected numbering and bullet point styles for consistency.

---

Changes walkthrough 📝

Relevant files

Documentation

13 files metadata.md Standardized numbering and improved readability.                  +4/-4      analyze.md Updated note formatting for supported languages.                  +2/-3      ask.md Corrected numbering format for instructions.                          +4/-4      custom_prompt.md Adjusted bullet formatting for configuration options.        +3/-3      describe.md Replaced arrow symbol with descriptive text.                          +1/-1      documentation.md Standardized note formatting and improved clarity.              +3/-4      implement.md Improved formatting for reviewer instructions and configuration options. +8/-6      improve.md Standardized note formatting and improved section clarity. +6/-10    improve_component.md Updated note formatting for supported languages.                  +3/-3      similar_issues.md Enhanced configuration instructions for vector databases. +6/-3      test.md Standardized note formatting for supported languages.        +3/-3      automations_and_usage.md Improved clarity in CLI usage examples and notes.                +4/-9      changing_a_model.md Corrected numbering and improved configuration instructions. +4/-4

---

Need help?

Type /help how to ... in the comments thread for any questions about Qodo Merge usage.

Check out the documentation for more information.

[ofir-frd]

/describe
--pr_description.generate_ai_title=true

[qodo-merge-pro-for-open-source]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ No major issues detected

[qodo-merge-pro-for-open-source]

PR Description updated to latest commit (5bace4d)

• Copy walkthrough table to "Files Changed" Tab

[qodo-merge-pro-for-open-source]

PR Code Suggestions ✨

Latest suggestions up to 5bace4d

Category	Suggestion	Impact
Learned best practice	Improve documentation readability by using consistent header formatting and clear section organization The section headers and formatting are inconsistent. The "Select VectorDBs" section should use consistent header formatting and clear section organization like the improved version, which uses proper header hierarchy and formatting. docs/docs/tools/similar_issues.md [19-24] -**Select VectorDBs** by changing `pr_similar_issue` parameter in `configuration.toml` file +### Selecting a Vector Database +Configure your preferred database by changing the `pr_similar_issue` parameter in `configuration.toml` file. -2 VectorDBs are available to switch in +#### Available Options +Choose from the following Vector Databases: + 1. LanceDB 2. Pinecone [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 6	Low
General	Remove redundant heading The heading "Available Options" is redundant since it's immediately followed by a numbered list of options. Remove it to improve document flow and reduce redundancy. docs/docs/tools/similar_issues.md [22-26] -#### Available Options Choose from the following Vector Databases: 1. LanceDB 2. Pinecone Apply this suggestion Suggestion importance[1-10]: 3 __ Why: The suggestion proposes a minor improvement to document readability by removing redundant heading, but the impact is relatively low as it's just a formatting change that doesn't affect functionality.	Low
Update

• Author self-review: I have reviewed the PR code suggestions, and addressed the relevant ones.

---

Previous suggestions

Suggestions up to commit 5bace4d

Category	Suggestion	Impact
Learned best practice	Format technical terms and enumerations consistently in documentation to improve readability and maintainability The list of supported git providers should be formatted consistently using backticks for each provider name and presented in a clear list format. This improves readability and maintains consistent technical term formatting. docs/docs/usage-guide/automations_and_usage.md [30-31] -3. **git provider**: The [git_provider](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L5) field in a configuration file determines the GIT provider that will be used by Qodo Merge. Currently, the following providers are supported: -`github` **(default)**, `gitlab`, `bitbucket`, `azure`, `codecommit`, `local`, and `gerrit`. +3. **Git Provider**: The [git_provider](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L5) field in a configuration file determines the Git provider that will be used by Qodo Merge. Currently, the following providers are supported: +- `github` (default) +- `gitlab` +- `bitbucket` +- `azure` +- `codecommit` +- `local` +- `gerrit` + Suggestion importance[1-10]: 6	Low
General	Fix inconsistent heading hierarchy The heading hierarchy is inconsistent. The "Available Options" section should be at the same level as "Pinecone Configuration" since they are both subsections under "Selecting a Vector Database". docs/docs/tools/similar_issues.md [19-28] ### Selecting a Vector Database Configure your preferred database by changing the `pr_similar_issue` parameter in `configuration.toml` file. -#### Available Options +### Available Options Choose from the following Vector Databases: 1. LanceDB 2. Pinecone -#### Pinecone Configuration +### Pinecone Configuration Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies a minor documentation structure issue where heading levels are inconsistent. While valid, this is a relatively low-impact change that only affects readability slightly.	Low

[ofir-frd]

/ask find typos

[qodo-merge-pro-for-open-source]

Ask❓

find typos

Answer:

Looking through the PR diff, I found only one minor typo:

In the file 'docs/docs/tools/documentation.md', there is a typo in the note syntax:

- !!! notes "Notes"
+ !!! note "Notes"

The correct syntax is !!! note (singular) rather than !!! notes (plural). This same typo appears in 'docs/docs/tools/test.md' as well.

These are the only typos I could find in the changes introduced by this PR. The rest of the formatting and text appears to be correct.

[qodo-merge-pro-for-open-source]

CI Feedback 🧐

(Feedback updated until commit af72b45)

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: build-and-test

Failed stage: Test dev docker [❌]

Failed test name: TestTicketCompliance.test_fetch_sub_issues

Failure summary: The action failed due to missing GitHub authentication configuration: Two test cases in TestTicketCompliance failed because the required GitHub user token was not found The tests expected a user_token setting but received a BoxKeyError: 'DynaBox' object has no attribute 'user_token' The error message indicates that GitHub token is required when using user deployment mode

Relevant error logs: 1: ##[group]Operating System 2: Ubuntu ... 1715: tests/unittest/test_find_line_number_of_relevant_line_in_file.py ...... [ 65%] 1716: tests/unittest/test_fix_output.py .... [ 69%] 1717: tests/unittest/test_github_action_output.py .... [ 74%] 1718: tests/unittest/test_handle_patch_deletions.py .... [ 78%] 1719: tests/unittest/test_language_handler.py ...... [ 84%] 1720: tests/unittest/test_load_yaml.py ... [ 88%] 1721: tests/unittest/test_parse_code_suggestion.py .... [ 92%] 1722: tests/unittest/test_try_fix_yaml.py ....... [100%] 1723: =================================== FAILURES =================================== 1724: __________________ TestTicketCompliance.test_fetch_sub_issues __________________ 1725: self = <pr_agent.git_providers.github_provider.GithubProvider object at 0x7ff9065a46e0> 1726: def _get_github_client(self): 1727: deployment_type = get_settings().get("GITHUB.DEPLOYMENT_TYPE", "user") 1728: if deployment_type == 'app': 1729: try: 1730: private_key = get_settings().github.private_key 1731: app_id = get_settings().github.app_id 1732: except AttributeError as e: 1733: raise ValueError("GitHub app ID and private key are required when using GitHub app deployment") from e 1734: if not self.installation_id: 1735: raise ValueError("GitHub app installation ID is required when using GitHub app deployment") ... 1747: return super().__getattr__(n_item, *args, **kwargs) 1748: _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 1749: A = <Box: {'deployment_type': 'user', 'ratelimit_retries': 5, 'base_url': 'https://api.github.com', 'publish_inline_commen...back_with_verification': True, 'try_fix_invalid_inline_comments': True, 'app_name': 'pr-agent', 'ignore_bot_pr': True}> 1750: item = 'user_token' 1751: def __getattr__(A,item): 1752: B=item 1753: try: 1754: try:C=A.__getitem__(B,_ignore_default=_G) 1755: except KeyError:C=object.__getattribute__(A,B) 1756: except AttributeError as E: 1757: if B=='__getstate__':raise BoxKeyError(B)from _A 1758: if B==_H:raise BoxError('_box_config key must exist')from _A 1759: if A._box_config[_E]: 1760: D=A._safe_attr(B) 1761: if D in A._box_config[_C]:return A.__getitem__(A._box_config[_C][D]) 1762: if A._box_config[_J]:return A.__get_default(B) 1763: > raise BoxKeyError(str(E))from _A 1764: E dynaconf.vendor.box.exceptions.BoxKeyError: "'DynaBox' object has no attribute 'user_token'" 1765: /usr/local/lib/python3.12/site-packages/dynaconf/vendor/box/box.py:176: BoxKeyError ... 1777: _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 1778: self = <pr_agent.git_providers.github_provider.GithubProvider object at 0x7ff9065a46e0> 1779: def _get_github_client(self): 1780: deployment_type = get_settings().get("GITHUB.DEPLOYMENT_TYPE", "user") 1781: if deployment_type == 'app': 1782: try: 1783: private_key = get_settings().github.private_key 1784: app_id = get_settings().github.app_id 1785: except AttributeError as e: 1786: raise ValueError("GitHub app ID and private key are required when using GitHub app deployment") from e 1787: if not self.installation_id: 1788: raise ValueError("GitHub app installation ID is required when using GitHub app deployment") 1789: auth = AppAuthentication(app_id=app_id, private_key=private_key, 1790: installation_id=self.installation_id) 1791: return Github(app_auth=auth, base_url=self.base_url) 1792: if deployment_type == 'user': 1793: try: 1794: token = get_settings().github.user_token 1795: except AttributeError as e: 1796: > raise ValueError( 1797: "GitHub token is required when using user deployment. See: " 1798: "https://github.com/Codium-ai/pr-agent#method-2-run-from-source") from e 1799: E ValueError: GitHub token is required when using user deployment. See: https://github.com/Codium-ai/pr-agent#method-2-run-from-source 1800: pr_agent/git_providers/github_provider.py:724: ValueError 1801: __________ TestTicketCompliance.test_fetch_sub_issues_with_no_results __________ 1802: self = <pr_agent.git_providers.github_provider.GithubProvider object at 0x7ff9074e4530> 1803: def _get_github_client(self): 1804: deployment_type = get_settings().get("GITHUB.DEPLOYMENT_TYPE", "user") 1805: if deployment_type == 'app': 1806: try: 1807: private_key = get_settings().github.private_key 1808: app_id = get_settings().github.app_id 1809: except AttributeError as e: 1810: raise ValueError("GitHub app ID and private key are required when using GitHub app deployment") from e 1811: if not self.installation_id: 1812: raise ValueError("GitHub app installation ID is required when using GitHub app deployment") ... 1824: return super().__getattr__(n_item, *args, **kwargs) 1825: _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 1826: A = <Box: {'deployment_type': 'user', 'ratelimit_retries': 5, 'base_url': 'https://api.github.com', 'publish_inline_commen...back_with_verification': True, 'try_fix_invalid_inline_comments': True, 'app_name': 'pr-agent', 'ignore_bot_pr': True}> 1827: item = 'user_token' 1828: def __getattr__(A,item): 1829: B=item 1830: try: 1831: try:C=A.__getitem__(B,_ignore_default=_G) 1832: except KeyError:C=object.__getattribute__(A,B) 1833: except AttributeError as E: 1834: if B=='__getstate__':raise BoxKeyError(B)from _A 1835: if B==_H:raise BoxError('_box_config key must exist')from _A 1836: if A._box_config[_E]: 1837: D=A._safe_attr(B) 1838: if D in A._box_config[_C]:return A.__getitem__(A._box_config[_C][D]) 1839: if A._box_config[_J]:return A.__get_default(B) 1840: > raise BoxKeyError(str(E))from _A 1841: E dynaconf.vendor.box.exceptions.BoxKeyError: "'DynaBox' object has no attribute 'user_token'" 1842: /usr/local/lib/python3.12/site-packages/dynaconf/vendor/box/box.py:176: BoxKeyError ... 1854: _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 1855: self = <pr_agent.git_providers.github_provider.GithubProvider object at 0x7ff9074e4530> 1856: def _get_github_client(self): 1857: deployment_type = get_settings().get("GITHUB.DEPLOYMENT_TYPE", "user") 1858: if deployment_type == 'app': 1859: try: 1860: private_key = get_settings().github.private_key 1861: app_id = get_settings().github.app_id 1862: except AttributeError as e: 1863: raise ValueError("GitHub app ID and private key are required when using GitHub app deployment") from e 1864: if not self.installation_id: 1865: raise ValueError("GitHub app installation ID is required when using GitHub app deployment") 1866: auth = AppAuthentication(app_id=app_id, private_key=private_key, 1867: installation_id=self.installation_id) 1868: return Github(app_auth=auth, base_url=self.base_url) 1869: if deployment_type == 'user': 1870: try: 1871: token = get_settings().github.user_token 1872: except AttributeError as e: 1873: > raise ValueError( 1874: "GitHub token is required when using user deployment. See: " 1875: "https://github.com/Codium-ai/pr-agent#method-2-run-from-source") from e 1876: E ValueError: GitHub token is required when using user deployment. See: https://github.com/Codium-ai/pr-agent#method-2-run-from-source 1877: pr_agent/git_providers/github_provider.py:724: ValueError ... 1905: ../usr/local/lib/python3.12/site-packages/pkg_resources/__init__.py:2317 1906: /usr/local/lib/python3.12/site-packages/pkg_resources/__init__.py:2317: DeprecationWarning: Deprecated call to `pkg_resources.declare_namespace('azure')`. 1907: Implementing implicit namespace packages (as specified in PEP 420) is preferred to `pkg_resources.declare_namespace`. See https://setuptools.pypa.io/en/latest/references/keywords.html#keyword-namespace-packages 1908: declare_namespace(parent) 1909: ../usr/local/lib/python3.12/site-packages/starlette/formparsers.py:12 1910: /usr/local/lib/python3.12/site-packages/starlette/formparsers.py:12: PendingDeprecationWarning: Please use `import python_multipart` instead. 1911: import multipart 1912: ../usr/local/lib/python3.12/site-packages/pydantic/_internal/_config.py:291 1913: /usr/local/lib/python3.12/site-packages/pydantic/_internal/_config.py:291: PydanticDeprecatedSince20: Support for class-based `config` is deprecated, use ConfigDict instead. Deprecated in Pydantic V2.0 to be removed in V3.0. See Pydantic V2 Migration Guide at https://errors.pydantic.dev/2.8/migration/ ... 2002: pr_agent/tools/pr_reviewer.py 225 225 0% 2003: pr_agent/tools/pr_similar_issue.py 363 363 0% 2004: pr_agent/tools/pr_update_changelog.py 110 110 0% 2005: pr_agent/tools/ticket_pr_compliance_check.py 99 88 11% 2006: --------------------------------------------------------------------------------------- 2007: TOTAL 9207 7610 17% 2008: Coverage XML written to file coverage.xml 2009: =========================== short test summary info ============================ 2010: FAILED tests/unittest/test_fetching_sub_issues.py::TestTicketCompliance::test_fetch_sub_issues 2011: FAILED tests/unittest/test_fetching_sub_issues.py::TestTicketCompliance::test_fetch_sub_issues_with_no_results 2012: ================== 2 failed, 91 passed, 19 warnings in 11.58s ================== 2013: ##[error]Process completed with exit code 1.