From 919d326ee5254095d438311f07fa5361bdf21039 Mon Sep 17 00:00:00 2001 From: Altay Sansal Date: Thu, 20 Jul 2023 17:48:13 -0500 Subject: [PATCH 1/5] Upgrade versionImprove code readability and update dependencies This commit makes several improvements with the goal of enhancing code maintainability. Several import statements have been reorganized for consistency and improved readability. ruamel.yaml package usage has been replaced with yaml PyYAML parsing. This decision was made due to its wider usage, more frequent updates, and better integration. This change also necessitates updates in requirement.txt and setup.py. Unit and UAT tests have been updated to reflect these changes. Mkdoxy version has been bumped from 1.1.5 to 1.1.6 to indicate these changes. --- mkdoxy/DoxyTagParser.py | 1 + mkdoxy/doxyrun.py | 4 ++-- mkdoxy/finder.py | 4 +++- mkdoxy/generatorBase.py | 11 ++++++++--- mkdoxy/generatorSnippets.py | 15 +++++---------- mkdoxy/markdown.py | 1 + mkdoxy/node.py | 2 +- mkdoxy/plugin.py | 3 +-- mkdoxy/utils.py | 8 +++----- mkdoxy/xml_parser.py | 21 +++++++++++++++++++-- requirements.txt | 1 - setup.py | 5 +++-- tests-old/metaDataParse.py | 8 ++++---- tests-old/parseMdTags.py | 5 ++--- 14 files changed, 53 insertions(+), 36 deletions(-) diff --git a/mkdoxy/DoxyTagParser.py b/mkdoxy/DoxyTagParser.py index df9d439c..a7c098d1 100644 --- a/mkdoxy/DoxyTagParser.py +++ b/mkdoxy/DoxyTagParser.py @@ -1,5 +1,6 @@ import re + class DoxyTagParser: def __init__( diff --git a/mkdoxy/doxyrun.py b/mkdoxy/doxyrun.py index 0f0fd026..7d54d1eb 100644 --- a/mkdoxy/doxyrun.py +++ b/mkdoxy/doxyrun.py @@ -1,8 +1,8 @@ import hashlib import logging -import tempfile + from pathlib import Path, PurePath -from subprocess import Popen, PIPE +from subprocess import PIPE, Popen from typing import Optional log: logging.Logger = logging.getLogger("mkdocs") diff --git a/mkdoxy/finder.py b/mkdoxy/finder.py index 81e9529f..2de9df8f 100644 --- a/mkdoxy/finder.py +++ b/mkdoxy/finder.py @@ -1,7 +1,9 @@ +from typing import Dict + from mkdoxy.constants import Kind from mkdoxy.doxygen import Doxygen from mkdoxy.utils import recursive_find, recursive_find_with_parent -from typing import Dict + class Finder: def __init__(self, doxygen: Dict[str, Doxygen], debug: bool = False): diff --git a/mkdoxy/generatorBase.py b/mkdoxy/generatorBase.py index 999b2dd4..32ab9496 100644 --- a/mkdoxy/generatorBase.py +++ b/mkdoxy/generatorBase.py @@ -3,14 +3,19 @@ import string from typing import Dict -from jinja2 import Template, FileSystemLoader, Environment, ChoiceLoader +from jinja2 import Template from jinja2.exceptions import TemplateError from mkdocs import exceptions import mkdoxy from mkdoxy.constants import Kind -from mkdoxy.node import Node, DummyNode -from mkdoxy.utils import parseTemplateFile, merge_two_dicts, recursive_find_with_parent, recursive_find +from mkdoxy.node import DummyNode, Node +from mkdoxy.utils import ( + merge_two_dicts, + parseTemplateFile, + recursive_find, + recursive_find_with_parent, +) log: logging.Logger = logging.getLogger("mkdocs") diff --git a/mkdoxy/generatorSnippets.py b/mkdoxy/generatorSnippets.py index 81e50f3c..b5984e37 100644 --- a/mkdoxy/generatorSnippets.py +++ b/mkdoxy/generatorSnippets.py @@ -1,17 +1,13 @@ import logging import pathlib import re -import string -from pprint import * -from mkdocs.config import Config +import yaml from mkdocs.structure import pages -from mkdoxy.doxygen import Doxygen - -from mkdoxy.generatorBase import GeneratorBase -from ruamel.yaml import YAML, YAMLError +from mkdoxy.doxygen import Doxygen from mkdoxy.finder import Finder +from mkdoxy.generatorBase import GeneratorBase from mkdoxy.node import Node log: logging.Logger = logging.getLogger("mkdocs") @@ -112,9 +108,8 @@ def generate(self): def try_load_yaml(self, yaml_raw: str, project: str, snippet: str, config: dict) -> dict: try: - yaml = YAML() - return yaml.load(yaml_raw) - except YAMLError as e: + return yaml.safe_load(yaml_raw) + except yaml.YAMLError as e: log.error(f"YAML error in {project} project on page {self.page.url}") self.doxyError( project, diff --git a/mkdoxy/markdown.py b/mkdoxy/markdown.py index e262bf75..69948848 100644 --- a/mkdoxy/markdown.py +++ b/mkdoxy/markdown.py @@ -1,5 +1,6 @@ from typing import List + def escape(s: str) -> str: ret = s.replace('*', '\\*') ret = ret.replace('_', '\\_') diff --git a/mkdoxy/node.py b/mkdoxy/node.py index 1b8fd47e..fa8e6734 100644 --- a/mkdoxy/node.py +++ b/mkdoxy/node.py @@ -4,7 +4,7 @@ from xml.etree.ElementTree import Element as Element from mkdoxy.cache import Cache -from mkdoxy.constants import Kind, Visibility, OVERLOAD_OPERATORS +from mkdoxy.constants import OVERLOAD_OPERATORS, Kind, Visibility from mkdoxy.markdown import escape from mkdoxy.property import Property from mkdoxy.utils import split_safe diff --git a/mkdoxy/plugin.py b/mkdoxy/plugin.py index 7df288b0..077fe40b 100644 --- a/mkdoxy/plugin.py +++ b/mkdoxy/plugin.py @@ -9,7 +9,7 @@ from pathlib import Path, PurePath from mkdocs import exceptions -from mkdocs.config import base, config_options, Config +from mkdocs.config import Config, base, config_options from mkdocs.plugins import BasePlugin from mkdocs.structure import files, pages @@ -19,7 +19,6 @@ from mkdoxy.generatorAuto import GeneratorAuto from mkdoxy.generatorBase import GeneratorBase from mkdoxy.generatorSnippets import GeneratorSnippets -from mkdoxy.utils import check_enabled_markdown_extensions from mkdoxy.xml_parser import XmlParser log: logging.Logger = logging.getLogger("mkdocs") diff --git a/mkdoxy/utils.py b/mkdoxy/utils.py index 34c6476b..180d403a 100644 --- a/mkdoxy/utils.py +++ b/mkdoxy/utils.py @@ -1,8 +1,8 @@ import logging import re +import yaml from mkdocs.config import Config -from ruamel.yaml import YAML log: logging.Logger = logging.getLogger("mkdocs") @@ -73,10 +73,8 @@ def parseTemplateFile(templateFile: str): if match: template = match["template"] meta = match["meta"] - yaml = YAML(typ='safe') - metaData = yaml.load(meta) - # yaml.dump(metaData, sys.stdout) - return template, metaData + metadata = yaml.safe_load(meta) + return template, metadata return templateFile, {} diff --git a/mkdoxy/xml_parser.py b/mkdoxy/xml_parser.py index cf7702f3..b77cca47 100644 --- a/mkdoxy/xml_parser.py +++ b/mkdoxy/xml_parser.py @@ -1,8 +1,25 @@ from xml.etree.ElementTree import Element as Element from mkdoxy.cache import Cache -from mkdoxy.markdown import Md, MdRenderer, MdParagraph, MdTable, Code, MdTableRow, MdCodeBlock, MdTableCell, \ - MdHeader, MdImage, MdList, MdBlockQuote, MdLink, MdBold, MdItalic, Text, Br +from mkdoxy.markdown import ( + Br, + Code, + Md, + MdBlockQuote, + MdBold, + MdCodeBlock, + MdHeader, + MdImage, + MdItalic, + MdLink, + MdList, + MdParagraph, + MdRenderer, + MdTable, + MdTableCell, + MdTableRow, + Text, +) from mkdoxy.utils import lookahead SIMPLE_SECTIONS = { diff --git a/requirements.txt b/requirements.txt index 6292261d..016bb16d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,2 +1 @@ mkdocs -ruamel.yaml diff --git a/setup.py b/setup.py index e5cd479a..a0020fa3 100755 --- a/setup.py +++ b/setup.py @@ -11,7 +11,7 @@ def requirements(): # https://pypi.org/project/mkdoxy/ setup( name='mkdoxy', - version='1.1.5', + version='1.1.6', description='MkDoxy → MkDocs + Doxygen = easy documentation generator with code snippets', long_description=readme(), long_description_content_type='text/markdown', @@ -29,7 +29,7 @@ def requirements(): 'Funding': 'https://github.com/sponsors/jakubandrysek', }, - install_requires=['mkdocs', 'ruamel.yaml'], + install_requires=['mkdocs'], extras_require={ "dev": [ "mkdocs-material==9.1.18", @@ -38,6 +38,7 @@ def requirements(): "mkdocs-open-in-new-tab~=1.0.2", "pathlib~=1.0.1", "path~=16.7.1", + "isort~=5.12.0" ], }, classifiers=[ diff --git a/tests-old/metaDataParse.py b/tests-old/metaDataParse.py index 0c9f7469..7e0ed1eb 100644 --- a/tests-old/metaDataParse.py +++ b/tests-old/metaDataParse.py @@ -4,7 +4,8 @@ from markdown.extensions import meta import re from pprint import * -from ruamel.yaml import YAML +import yaml + text = """\ --- @@ -57,6 +58,5 @@ match = re.match(regex, text2, re.MULTILINE) meta = match.group("meta") -yaml = YAML(typ='safe') -config = yaml.load(meta) -yaml.dump(config, sys.stdout) \ No newline at end of file +config = yaml.safe_load(meta) +yaml.dump(config, sys.stdout) diff --git a/tests-old/parseMdTags.py b/tests-old/parseMdTags.py index ba79370e..f79210d1 100644 --- a/tests-old/parseMdTags.py +++ b/tests-old/parseMdTags.py @@ -1,7 +1,7 @@ import re import sys from pathlib import Path -from ruamel.yaml import YAML +import yaml def readFile(filename: str) -> str: @@ -28,8 +28,7 @@ def readFile(filename: str) -> str: yamlRaw = match.group('yaml') if yamlRaw: try: - yaml = YAML() - config = yaml.load(yamlRaw) + config = yaml.safe_load(yamlRaw) yaml.dump(config, sys.stdout) except yaml.YAMLError as e: print(e) From 4ed4b55bc039f4f2d260c85a89b6e239209a14e0 Mon Sep 17 00:00:00 2001 From: Altay Sansal Date: Thu, 20 Jul 2023 17:50:00 -0500 Subject: [PATCH 2/5] Remove ruamel.yaml from dev dependencies The library 'ruamel.yaml' was removed from the development dependencies in setup.py. This was done because it's no longer necessary for the current version of the application. The application's functionality should remain unaffected. --- setup.py | 1 - 1 file changed, 1 deletion(-) diff --git a/setup.py b/setup.py index a0020fa3..d8ce5184 100755 --- a/setup.py +++ b/setup.py @@ -34,7 +34,6 @@ def requirements(): "dev": [ "mkdocs-material==9.1.18", "Jinja2~=3.1.2", - "ruamel.yaml~=0.17.32", "mkdocs-open-in-new-tab~=1.0.2", "pathlib~=1.0.1", "path~=16.7.1", From ede67b748759798100cf07d8321a57f369262d14 Mon Sep 17 00:00:00 2001 From: Altay Sansal Date: Thu, 20 Jul 2023 18:02:58 -0500 Subject: [PATCH 3/5] update changelog --- CHANGELOG.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e33be1eb..564d1299 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,4 +8,8 @@ All notable changes to this project will be documented in this file. - **v1.0.5** - 2023-04-01 - Add support for [custom templates](https://github.com/JakubAndrysek/MkDoxy/pull/39) - **v1.0.6** - 2023-04-01 - - Add support disable plugin [using environment variable](#disabling-the-plugin) \ No newline at end of file + - Add support disable plugin [using environment variable](#disabling-the-plugin) +- **v1.1.6** - 2023-07-20 + - Replace `ruamel.yaml` with `pyyaml`. [#73](https://github.com/JakubAndrysek/MkDoxy/pull/73) + - Add `isort` as dev dependency. [#73](https://github.com/JakubAndrysek/MkDoxy/pull/73) + - Sort and cleanup imports [#73](https://github.com/JakubAndrysek/MkDoxy/pull/73) From a98eb70d741a1c1fcf597b74d7e3463beaffde5b Mon Sep 17 00:00:00 2001 From: Altay Sansal Date: Thu, 20 Jul 2023 18:04:17 -0500 Subject: [PATCH 4/5] Replace `m.group(x)`` with `m[x]`` for re.Match objects --- tests-old/metaDataParse.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests-old/metaDataParse.py b/tests-old/metaDataParse.py index 7e0ed1eb..9675d338 100644 --- a/tests-old/metaDataParse.py +++ b/tests-old/metaDataParse.py @@ -57,6 +57,6 @@ match = re.match(regex, text2, re.MULTILINE) -meta = match.group("meta") +meta = match["meta"] config = yaml.safe_load(meta) yaml.dump(config, sys.stdout) From e787a38f1d5ea49814f39108bd1896398d9b583e Mon Sep 17 00:00:00 2001 From: Altay Sansal Date: Thu, 20 Jul 2023 18:09:09 -0500 Subject: [PATCH 5/5] yaml.safe_dump instead of yaml.dump --- tests-old/metaDataParse.py | 2 +- tests-old/parseMdTags.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests-old/metaDataParse.py b/tests-old/metaDataParse.py index 9675d338..5e0ba623 100644 --- a/tests-old/metaDataParse.py +++ b/tests-old/metaDataParse.py @@ -59,4 +59,4 @@ match = re.match(regex, text2, re.MULTILINE) meta = match["meta"] config = yaml.safe_load(meta) -yaml.dump(config, sys.stdout) +yaml.safe_dump(config, sys.stdout) diff --git a/tests-old/parseMdTags.py b/tests-old/parseMdTags.py index f79210d1..01e05446 100644 --- a/tests-old/parseMdTags.py +++ b/tests-old/parseMdTags.py @@ -29,7 +29,7 @@ def readFile(filename: str) -> str: if yamlRaw: try: config = yaml.safe_load(yamlRaw) - yaml.dump(config, sys.stdout) + yaml.safe_dump(config, sys.stdout) except yaml.YAMLError as e: print(e) print() \ No newline at end of file