diff --git a/docs/ADD_DOCUMENTATION.md b/docs/ADD_DOCUMENTATION.md new file mode 100644 index 00000000..333352e8 --- /dev/null +++ b/docs/ADD_DOCUMENTATION.md @@ -0,0 +1,14 @@ +# Add Documentation Tool +The `add_docs` tool scans the PR code changes, and automatically suggests documentation for the undocumented code components (functions, classes, etc.). + +It can be invoked manually by commenting on any PR: +``` +/add_docs +``` +For example: + + + +### Configuration options + - `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 ...". \ No newline at end of file diff --git a/docs/TOOLS_GUIDE.md b/docs/TOOLS_GUIDE.md index 352195bc..b3831961 100644 --- a/docs/TOOLS_GUIDE.md +++ b/docs/TOOLS_GUIDE.md @@ -5,5 +5,6 @@ - [ASK](./ASK.md) - [SIMILAR_ISSUE](./SIMILAR_ISSUE.md) - [UPDATE CHANGELOG](./UPDATE_CHANGELOG.md) +- [ADD DOCUMENTATION](./ADD_DOCUMENTATION.md) See the **[installation guide](/INSTALL.md)** for instructions on how to setup PR-Agent. \ No newline at end of file diff --git a/pics/add_docs.png b/pics/add_docs.png new file mode 100644 index 00000000..143ae49b Binary files /dev/null and b/pics/add_docs.png differ diff --git a/pics/add_docs_comment.png b/pics/add_docs_comment.png new file mode 100644 index 00000000..cd40ff12 Binary files /dev/null and b/pics/add_docs_comment.png differ diff --git a/pr_agent/settings/configuration.toml b/pr_agent/settings/configuration.toml index c807698b..187ded56 100644 --- a/pr_agent/settings/configuration.toml +++ b/pr_agent/settings/configuration.toml @@ -49,8 +49,7 @@ final_clip_factor = 0.9 [pr_add_docs] # /add_docs # extra_instructions = "" -docs_style = "Google Style" # "Google Style", "Numpy Style", "Sphinx Style", "PEP257", "reStructuredText" -max_number_of_calls = 5 +docs_style = "Sphinx Style" # "Google Style with Args, Returns, Attributes...etc", "Numpy Style", "Sphinx Style", "PEP257", "reStructuredText" [pr_update_changelog] # /update_changelog # push_changelog_changes=false diff --git a/pr_agent/settings/pr_add_docs.toml b/pr_agent/settings/pr_add_docs.toml index 4988b7fa..b552ec86 100644 --- a/pr_agent/settings/pr_add_docs.toml +++ b/pr_agent/settings/pr_add_docs.toml @@ -32,7 +32,7 @@ __old hunk__ Specific instructions: - Try to identify edited/added code components (classes/functions/methods...) that are undocumented. and generate {{ docs_for_language }} for each one. -- If there are edited/added code components, but they are already documented, ignore them. +- If there are documented (any type of {{ language }} documentation) code components in the PR, Don't generate {{ docs_for_language }} for them. - Ignore code components that don't appear fully in the '__new hunk__' section. For example. you must see the component header and body, - Make sure the {{ docs_for_language }} starts and ends with standart {{ language }} {{ docs_for_language }} signs. - The {{ docs_for_language }} should be in standard format. diff --git a/pr_agent/tools/pr_add_docs.py b/pr_agent/tools/pr_add_docs.py index fa78a92f..4cc9102a 100644 --- a/pr_agent/tools/pr_add_docs.py +++ b/pr_agent/tools/pr_add_docs.py @@ -21,12 +21,6 @@ class PRAddDocs: self.git_provider.get_languages(), self.git_provider.get_files() ) - # extended mode - try: - self.is_extended = any(["extended" in arg for arg in args]) - except: - self.is_extended = False - self.ai_handler = AiHandler() self.patches_diff = None self.prediction = None @@ -51,20 +45,17 @@ class PRAddDocs: try: logging.info('Generating code Docs for PR...') if get_settings().config.publish_output: - self.git_provider.publish_comment("Preparing review...", is_temporary=True) + self.git_provider.publish_comment("Generating Documentation...", is_temporary=True) - logging.info('Preparing PR review...') - if not self.is_extended: - await retry_with_fallback_models(self._prepare_prediction) - data = self._prepare_pr_code_docs() - else: - data = await retry_with_fallback_models(self._prepare_prediction_extended) + logging.info('Preparing PR documentation...') + await retry_with_fallback_models(self._prepare_prediction) + data = self._prepare_pr_code_docs() if (not data) or (not 'Code Documentation' in data): logging.info('No code documentation found for PR.') return if get_settings().config.publish_output: - logging.info('Pushing PR review...') + logging.info('Pushing PR documentation...') self.git_provider.remove_initial_comment() logging.info('Pushing inline code documentation...') self.push_inline_docs(data) @@ -97,8 +88,8 @@ class PRAddDocs: return response def _prepare_pr_code_docs(self) -> Dict: - review = self.prediction.strip() - data = load_yaml(review) + docs = self.prediction.strip() + data = load_yaml(docs) if isinstance(data, list): data = {'Code Documentation': data} return data @@ -167,37 +158,7 @@ class PRAddDocs: return new_code_snippet - async def _prepare_prediction_extended(self, model: str) -> dict: - logging.info('Getting PR diff...') - patches_diff_list = get_pr_multi_diffs(self.git_provider, self.token_handler, model, - max_calls=get_settings().pr_add_docs.max_number_of_calls) - logging.info('Getting multi AI predictions...') - prediction_list = [] - for i, patches_diff in enumerate(patches_diff_list): - logging.info(f"Processing chunk {i + 1} of {len(patches_diff_list)}") - self.patches_diff = patches_diff - prediction = await self._get_prediction(model) - prediction_list.append(prediction) - self.prediction_list = prediction_list - - data = {} - for prediction in prediction_list: - self.prediction = prediction - data_per_chunk = self._prepare_pr_code_docs() - if "Code Documentation" in data: - data["Code Documentation"].extend(data_per_chunk["Code Documentation"]) - else: - data.update(data_per_chunk) - self.data = data - return data - - -""" -This function determines the type of documentation to generate based on the main language of the PR. -It supports Javadocs for Java, Docstrings for Python, Lisp, and Clojure, JSdocs for JavaScript and TypeScript, -and Doxygen for C++. For other languages, it defaults to generating generic Docs. -""" def get_docs_for_language(language, style): language = language.lower() if language == 'java':