Update MkDoxy core #110

JakubAndrysek · 2024-06-21T12:41:27Z

Rewrite the core of MkDoxy plugin

improve config processing
mark outdated config options and add new ones
add migration tool to convert old config to new one

Summary by Sourcery

This pull request rewrites the core of the MkDoxy plugin, improving configuration processing, marking outdated config options, and adding new ones. It also introduces a migration tool to convert old configurations to the new format, enhances logging and error handling, and refactors the template loading mechanism.

New Features:
- Introduced a migration tool to convert old configuration to the new format.
- Added support for new configuration options in the MkDoxy plugin.
Enhancements:
- Improved configuration processing by consolidating and updating configuration options.
- Refactored the Doxygen run logic into a new DoxygenGenerator class.
- Updated the plugin to use new configuration keys and deprecated old ones.
- Enhanced logging and error handling for configuration validation.
- Refactored the template loading mechanism to support custom templates more effectively.
Tests:
- Added new tests for the migration tool to ensure correct conversion of old configuration files.
- Updated existing tests to align with the new DoxygenGenerator class and configuration changes.

sourcery-ai · 2024-06-21T12:41:40Z

Reviewer's Guide by Sourcery

This pull request rewrites the core of the MkDoxy plugin to improve configuration processing, mark outdated config options, and add new ones. It also introduces a migration tool to convert old config to the new format. The changes include refactoring classes and methods to use the new configuration structure, updating method names to follow snake_case convention, adding detailed docstrings, and updating tests and documentation accordingly.

File-Level Changes

Files	Changes
`mkdoxy/plugin.py` `mkdoxy/generatorSnippets.py` `mkdoxy/doxyrun.py` `mkdoxy/generatorBase.py` `mkdoxy/utils.py` `mkdoxy/generatorAuto.py` `mkdoxy/node.py` `mkdoxy/finder.py` `mkdoxy/doxygen.py`	Refactored classes and methods to use new configuration structure, updated method names to follow snake_case convention, and added detailed docstrings.
`tests/test_doxyrun.py` `tests/test_migration.py` `tests/data/migration/mkdocs2-new.yaml` `tests/data/migration/mkdocs2-old.yaml` `tests/data/migration/mkdocs1-new.yaml` `tests/data/migration/mkdocs1-old.yaml`	Updated tests to use new configuration structure and added new tests for configuration migration.
`mkdocs.yml` `docs/usage/index.md` `setup.py` `README.md`	Updated configuration options to use new keys and added instructions for new features.
`mkdoxy/DoxyTagParser.py` `mkdoxy/constants.py` `mkdoxy/project.py` `mkdoxy/migration.py` `mkdoxy/cli.py`	Added new files and updated existing ones to support configuration migration and CLI commands.

Tips

Trigger a new Sourcery review by commenting @sourcery-ai review on the pull request.
You can change your review settings at any time by accessing your dashboard:
- Enable or disable the Sourcery-generated pull request summary or reviewer's guide;
- Change the review language;
You can always contact us if you have any questions or feedback.

sourcery-ai

Hey @JakubAndrysek - I've reviewed your changes and found some issues that need to be addressed.

Blocking issues:

Hard-coded Google Analytics property ID found. (link)
Hard-coded Google Analytics property ID found. (link)
Hard-coded Google Analytics property ID found. (link)
Hard-coded Google Analytics property ID found. (link)

Here's what I looked at during the review

🟡 General issues: 9 issues found
🔴 Security: 4 blocking issues
🟡 Testing: 2 issues found
🟡 Complexity: 1 issue found
🟢 Documentation: all looks good

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment to tell me if it was helpful.}

sourcery-ai · 2024-06-21T12:44:38Z

mkdoxy/plugin.py

+        self.doxy_config = process_configuration(self.config)

-    def on_files(self, files: files.Files, config: base.Config) -> files.Files:
+        log.info(f"Start plugin {plugin_name}")


suggestion: Configuration processing

The process_configuration function is called to process the plugin configuration. Ensure that this function handles all necessary validation and transformation of the configuration data.

Suggested change

self.doxy_config = process_configuration(self.config)

def on_files(self, files: files.Files, config: base.Config) -> files.Files:

log.info(f"Start plugin {plugin_name}")

try:

self.doxy_config = process_configuration(self.config)

except Exception as e:

log.error(f"Configuration processing failed: {e}")

raise

log.info(f"Start plugin {plugin_name}")

sourcery-ai · 2024-06-21T12:44:38Z

mkdoxy/plugin.py

+            project_data: MkDoxyConfigProject
+            log.info(f"-> Processing project '{project_name}'")


suggestion: Type hint for project_data

The project_data variable is type hinted as MkDoxyConfigProject. Ensure that this type hint is accurate and that MkDoxyConfigProject is correctly defined.

Suggested change

project_data: MkDoxyConfigProject

log.info(f"-> Processing project '{project_name}'")

project_data = self.doxy_config.projects[project_name]

if not isinstance(project_data, MkDoxyConfigProject):

raise TypeError(f"Expected MkDoxyConfigProject, got {type(project_data).__name__}")

log.info(f"-> Processing project '{project_name}'")

sourcery-ai · 2024-06-21T12:44:38Z

mkdoxy/plugin.py

+            temp_doxy_folder.mkdir(parents=True, exist_ok=True)

            # Check src changes -> run Doxygen
-            doxygenRun = DoxygenRun(
-                self.config["doxygen-bin-path"],
-                project_data.get("src-dirs"),
-                tempDirApi,
-                project_data.get("doxy-cfg", {}),
-                project_data.get("doxy-cfg-file", ""),
+            doxygen = DoxygenGenerator(


issue (bug_risk): Directory creation

The temp_doxy_folder directory is created if it does not exist. Ensure that this operation is thread-safe if the plugin is used in a multi-threaded environment.

sourcery-ai · 2024-06-21T12:44:38Z

mkdoxy/doxyrun.py

+        hash_file_path = Path.joinpath(self.temp_doxy_folder, self.hash_file_name)
+        if hash_file_path.is_file():


suggestion: Hash file path construction

The hash_file_path is constructed using Path.joinpath. Ensure that this method is used consistently throughout the code for path manipulations.

sourcery-ai · 2024-06-21T12:44:39Z

mkdoxy/generatorBase.py

+        self.load_template_from_folder(path)
+
+        # test if custom template directory exists
+        if custom_template_dir:


suggestion: Loading templates from folder

The load_template_from_folder method is called to load templates from the specified folder. Ensure that this method handles all edge cases and errors gracefully.

sourcery-ai · 2024-06-21T12:44:40Z

tests/data/migration/mkdocs2-old.yaml

+      link: https://www.linkedin.com/in/jakub-andrysek/
+  analytics:
+    provider: google
+    property: G-8WHJ2N4SHC


🚨 issue (security): Hard-coded Google Analytics property ID found.

Consider using an environment variable to store the Google Analytics property ID to avoid exposing it in the source code.

sourcery-ai · 2024-06-21T12:44:40Z

tests/data/migration/mkdocs1-new.yaml

+      link: https://www.linkedin.com/in/jakub-andrysek/
+  analytics:
+    provider: google
+    property: G-8WHJ2N4SHC


🚨 issue (security): Hard-coded Google Analytics property ID found.

Consider using an environment variable to store the Google Analytics property ID to avoid exposing it in the source code.

sourcery-ai · 2024-06-21T12:44:40Z

tests/data/migration/mkdocs1-old.yaml

+      link: https://www.linkedin.com/in/jakub-andrysek/
+  analytics:
+    provider: google
+    property: G-8WHJ2N4SHC


🚨 issue (security): Hard-coded Google Analytics property ID found.

Consider using an environment variable to store the Google Analytics property ID to avoid exposing it in the source code.

sourcery-ai · 2024-06-21T12:44:40Z

mkdoxy/doxy_config.py

+    @return: None
+    @throws ConfigurationError: If the configuration is invalid.
+    """
+    if len(legacy_options) > 0:


suggestion (code-quality): Simplify sequence length comparison (simplify-len-comparison)

Suggested change

if len(legacy_options) > 0:

if legacy_options:

sourcery-ai · 2024-06-21T12:44:40Z

mkdoxy/doxygen.py

@@ -12,9 +13,9 @@


 class Doxygen:
-    def __init__(self, index_path: str, parser: XmlParser, cache: Cache):
+    def __init__(self, index_path: Path, parser: XmlParser, cache: Cache):


issue (code-quality): Low code quality found in Doxygen.__init__ - 23% (low-code-quality)

Explanation
The quality score for this function is below the quality threshold of 25%.
This score is a combination of the method length, cognitive complexity and working memory.

How can you solve this?

It might be worth refactoring this function to make it shorter and more readable.

Reduce the function length by extracting pieces of functionality out into
their own functions. This is the most important thing you can do - ideally a
function should be less than 10 lines.

Reduce nesting, perhaps by introducing guard clauses to return early.

Ensure that variables are tightly scoped, so that code using related concepts
sits together within the function rather than being scattered.

…ommit hooks

…own, return to old lint

JakubAndrysek added 5 commits June 19, 2024 11:19

Update MkDoxy core

6673681

Fix imports

bf58ed5

Update MkDoxy-demo tests

d625ef1

Add migration tool

21320f9

Rewrite config validation schema

91126f4

JakubAndrysek marked this pull request as ready for review June 21, 2024 12:41

sourcery-ai bot reviewed Jun 21, 2024

View reviewed changes

JakubAndrysek added 2 commits June 21, 2024 15:05

Reformat with sourcery

e919dbf

chore: Update lint.yaml to include Python environment setup and pre-c…

d24072a

…ommit hooks

JakubAndrysek force-pushed the core-update branch from 9d74b55 to d24072a Compare June 21, 2024 13:15

JakubAndrysek added 3 commits June 21, 2024 15:20

chore: Update Python environment setup and dependencies in lint.yaml

239cdac

chore: Fix escape function to properly handle pipe character in markd…

fefb698

…own, return to old lint

To review

4a57265

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update MkDoxy core #110

Update MkDoxy core #110

JakubAndrysek commented Jun 21, 2024 •

edited by sourcery-ai bot

Loading

sourcery-ai bot commented Jun 21, 2024 •

edited

Loading

sourcery-ai bot left a comment

sourcery-ai bot Jun 21, 2024

sourcery-ai bot Jun 21, 2024

sourcery-ai bot Jun 21, 2024

sourcery-ai bot Jun 21, 2024

sourcery-ai bot Jun 21, 2024

sourcery-ai bot Jun 21, 2024

sourcery-ai bot Jun 21, 2024

sourcery-ai bot Jun 21, 2024

sourcery-ai bot Jun 21, 2024

sourcery-ai bot Jun 21, 2024

		project_data: MkDoxyConfigProject
		log.info(f"-> Processing project '{project_name}'")

		hash_file_path = Path.joinpath(self.temp_doxy_folder, self.hash_file_name)
		if hash_file_path.is_file():

Update MkDoxy core #110

Are you sure you want to change the base?

Update MkDoxy core #110

Conversation

JakubAndrysek commented Jun 21, 2024 • edited by sourcery-ai bot Loading

Summary by Sourcery

sourcery-ai bot commented Jun 21, 2024 • edited Loading

Reviewer's Guide by Sourcery

File-Level Changes

sourcery-ai bot left a comment

Choose a reason for hiding this comment

sourcery-ai bot Jun 21, 2024

Choose a reason for hiding this comment

sourcery-ai bot Jun 21, 2024

Choose a reason for hiding this comment

sourcery-ai bot Jun 21, 2024

Choose a reason for hiding this comment

sourcery-ai bot Jun 21, 2024

Choose a reason for hiding this comment

sourcery-ai bot Jun 21, 2024

Choose a reason for hiding this comment

sourcery-ai bot Jun 21, 2024

Choose a reason for hiding this comment

sourcery-ai bot Jun 21, 2024

Choose a reason for hiding this comment

sourcery-ai bot Jun 21, 2024

Choose a reason for hiding this comment

sourcery-ai bot Jun 21, 2024

Choose a reason for hiding this comment

sourcery-ai bot Jun 21, 2024

Choose a reason for hiding this comment

JakubAndrysek commented Jun 21, 2024 •

edited by sourcery-ai bot

Loading

sourcery-ai bot commented Jun 21, 2024 •

edited

Loading