Skip to content

Commit e18a8f3

Browse files
JakubAndrysekJakubAndrysek
committed
Add CLI tool for MkDoxy configuration migration and update dependencies
1 parent e2f8f29 commit e18a8f3

File tree

10 files changed

+1019
-1
lines changed

10 files changed

+1019
-1
lines changed

‎devdeps.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,4 @@ setuptools~=70.0.0
88
build~=1.2.2
99
twine~=5.1.1
1010
sourcery~=1.34.0
11+
click~=8.1.8

‎mkdoxy/__main__.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#!/usr/bin/env python
2+
from mkdoxy.cli import main
3+
4+
if __name__ == "__main__":
5+
main()

‎mkdoxy/cli.py

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
#!/usr/bin/env python
2+
from pathlib import Path
3+
import click
4+
from mkdoxy.migration import update_new_config
5+
6+
7+
@click.group()
8+
def main():
9+
"""mkdoxy - Command line tool for managing Doxygen configuration migration."""
10+
pass
11+
12+
13+
@click.command()
14+
@click.argument("yaml_file", type=click.Path(exists=True))
15+
@click.option("--no-backup", is_flag=True, help="Do not backup old config to mkdocs.1_old.yaml")
16+
def migrate(yaml_file, no_backup):
17+
"""
18+
Migrate mkdoxy configuration to a new version.
19+
20+
:param yaml_file: Path to the mkdocs.yaml file.
21+
:param no_backup: Do not backup the old config to mkdocs.1_old.yaml.
22+
"""
23+
backup_file_name = "mkdocs.1_old.yaml"
24+
update_new_config(Path(yaml_file), not no_backup, backup_file_name)
25+
click.echo("Migration completed successfully")
26+
if not no_backup:
27+
click.echo(f"Old config was backed up as '{backup_file_name}'")
28+
29+
30+
@click.command()
31+
def version():
32+
"""
33+
Display the version of the mkdoxy package.
34+
"""
35+
try:
36+
import importlib.metadata
37+
38+
package_version = importlib.metadata.version("mkdoxy")
39+
except Exception:
40+
package_version = "Unknown"
41+
click.echo("MkDoxy: https://github.com/JakubAndrysek/MkDoxy")
42+
click.echo(f"Version: {package_version}")
43+
44+
45+
main.add_command(migrate)
46+
main.add_command(version)
47+
48+
if __name__ == "__main__":
49+
main()

‎mkdoxy/migration.py

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import logging
2+
import re
3+
import shutil
4+
from pathlib import Path
5+
6+
log = logging.getLogger("mkdoxy.migration")
7+
8+
9+
def update_new_config(yaml_file: Path, backup: bool, backup_file_name: str) -> None:
10+
"""
11+
Migrate MkDoxy configuration to the new version by replacing legacy keys
12+
directly in the text file—preserving comments and structure.
13+
14+
Legacy keys are replaced only on non-comment lines.
15+
16+
:param yaml_file: Path to the mkdocs YAML configuration file.
17+
:param backup: If True, a backup of the original file is created.
18+
:param backup_file_name: The filename to use for the backup.
19+
"""
20+
if backup:
21+
backup_path = yaml_file.parent / backup_file_name
22+
shutil.copy2(yaml_file, backup_path)
23+
log.info(f"Backup created at {backup_path}")
24+
25+
text = yaml_file.read_text(encoding="utf-8")
26+
27+
# Merge global and project legacy mappings.
28+
legacy_mapping = {}
29+
legacy_mapping.update(
30+
{
31+
"full-doc": "full_doc",
32+
"ignore-errors": "ignore_errors",
33+
"save-api": "custom_api_folder",
34+
"doxygen-bin-path": "doxygen_bin_path",
35+
}
36+
)
37+
legacy_mapping.update(
38+
{
39+
"src-dirs": "src_dirs",
40+
"full-doc": "full_doc",
41+
"ignore-errors": "ignore_errors",
42+
"doxy-cfg": "doxy_config_dict",
43+
"doxy-cfg-file": "doxy_config_file",
44+
"template-dir": "custom_template_dir",
45+
}
46+
)
47+
48+
# Replace each legacy key only on lines that are not comments.
49+
for old_key, new_key in legacy_mapping.items():
50+
# Pattern matches lines that do not start with a comment (after optional whitespace),
51+
# then the legacy key followed by optional spaces and a colon.
52+
pattern = re.compile(rf"(?m)^(?!\s*#)(\s*){re.escape(old_key)}(\s*:)", re.UNICODE)
53+
text = pattern.sub(rf"\1{new_key}\2", text)
54+
55+
yaml_file.write_text(text, encoding="utf-8")
56+
log.info("Migration completed successfully")

‎setup.py

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,5 +59,10 @@ def import_dev_requirements():
5959
],
6060
packages=find_packages(),
6161
package_data={"mkdoxy": ["templates/*.jinja2"]},
62-
entry_points={"mkdocs.plugins": ["mkdoxy = mkdoxy.plugin:MkDoxy"]},
62+
entry_points={
63+
"mkdocs.plugins": ["mkdoxy = mkdoxy.plugin:MkDoxy"],
64+
# folder mkdoxy/cli.py
65+
# "console_scripts": ["mkdoxy = mkdoxy.cli:cli"],
66+
"console_scripts": ["mkdoxy = mkdoxy.__main__:main"],
67+
},
6368
)

‎tests/migration/data/1_expect.yaml

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
site_name: MkDoxy Demo
2+
site_url: https://mkdoxy-demo.kubaandrysek.cz/
3+
site_author: Jakub Andrýsek
4+
site_description: >-
5+
This is a demo of MkDoxy, a tool for generating Doxygen documentation from Markdown files.
6+
7+
# Repository
8+
repo_name: JakubAndrysek/MkDoxy-demo
9+
repo_url: https://github.com/JakubAndrysek/MkDoxy-demo
10+
11+
# Copyright
12+
copyright: Copyright © 2023 Jakub Andrýsek
13+
14+
theme:
15+
name: material
16+
language: en
17+
logo: assets/logo.png
18+
favicon: assets/logo.png
19+
features:
20+
- navigation.tabs
21+
- navigation.indexes
22+
- navigation.top
23+
- navigation.instant
24+
- navigation.tracking
25+
26+
icon:
27+
repo: fontawesome/brands/github
28+
29+
palette:
30+
# Palette toggle for dark mode
31+
- media: "(prefers-color-scheme: dark)"
32+
scheme: slate
33+
primary: amber
34+
accent: amber
35+
toggle:
36+
icon: material/brightness-4
37+
name: Switch to light mode
38+
39+
# Palette toggle for light mode
40+
- media: "(prefers-color-scheme: light)"
41+
scheme: default
42+
primary: amber
43+
accent: amber
44+
toggle:
45+
icon: material/brightness-7
46+
name: Switch to dark mode
47+
48+
extra:
49+
social:
50+
- icon: fontawesome/brands/github
51+
link: https://github.com/JakubAndrysek
52+
- icon: fontawesome/brands/twitter
53+
link: https://twitter.com/KubaAndrysek
54+
- icon: fontawesome/brands/linkedin
55+
link: https://www.linkedin.com/in/jakub-andrysek/
56+
analytics:
57+
provider: google
58+
property: G-6VB0GPP3MT
59+
feedback:
60+
title: Was this page helpful?
61+
ratings:
62+
- icon: material/emoticon-happy-outline
63+
name: This page was helpful
64+
data: 1
65+
note: >-
66+
Thanks for your feedback!
67+
- icon: material/emoticon-sad-outline
68+
name: This page could be improved
69+
data: 0
70+
note: >-
71+
Thanks for your feedback!
72+
73+
use_directory_urls: True
74+
#use_directory_urls: False
75+
76+
plugins:
77+
- search
78+
- glightbox
79+
- open-in-new-tab
80+
- mkdoxy:
81+
projects:
82+
esp:
83+
src_dirs: demo-projets/esp
84+
full_doc: True
85+
custom_template_dir: templates-custom
86+
# Example of custom template: https://mkdoxy-demo.kubaandrysek.cz/esp/annotated/
87+
doxy_config_dict:
88+
FILE_PATTERNS: "*.cpp *.h*"
89+
EXAMPLE_PATH: examples
90+
RECURSIVE: True
91+
animal:
92+
src_dirs: demo-projets/animal
93+
full_doc: True
94+
doxy_config_dict:
95+
FILE_PATTERNS: "*.cpp *.h*"
96+
EXAMPLE_PATH: examples
97+
RECURSIVE: True
98+
stm:
99+
src_dirs: demo-projets/stm32
100+
full_doc: True
101+
102+
jaculus:
103+
src_dirs: demo-projets/jaculus/main demo-projets/jaculus/managed_components/jac-link demo-projets/jaculus/managed_components/jac-machine
104+
full_doc: True
105+
doxy_config_dict:
106+
FILE_PATTERNS: "*.cpp *.h*"
107+
EXAMPLE_PATH: examples
108+
RECURSIVE: True
109+
110+
custom_api_folder: .mkdoxy
111+
full_doc: True
112+
debug: False
113+
ignore_errors: False
114+
115+
markdown_extensions:
116+
- pymdownx.highlight
117+
- pymdownx.superfences
118+
119+
nav:
120+
- "Home": "README.md"
121+
- useage.md
122+
- API Demo:
123+
- api/index.md
124+
- ESP-32:
125+
- esp/index.md
126+
- "Links": "esp/links.md"
127+
- "Classes":
128+
- "Class List": "esp/annotated.md"
129+
- "Class Index": "esp/classes.md"
130+
- "Class Hierarchy": "esp/hierarchy.md"
131+
- "Class Members": "esp/class_members.md"
132+
- "Class Member Functions": "esp/class_member_functions.md"
133+
- "Class Member Variables": "esp/class_member_variables.md"
134+
- "Class Member Typedefs": "esp/class_member_typedefs.md"
135+
- "Class Member Enumerations": "esp/class_member_enums.md"
136+
- "Namespaces":
137+
- "Namespace List": "esp/namespaces.md"
138+
- "Namespace Members": "esp/namespace_members.md"
139+
- "Namespace Member Functions": "esp/namespace_member_functions.md"
140+
- "Namespace Member Variables": "esp/namespace_member_variables.md"
141+
- "Namespace Member Typedefs": "esp/namespace_member_typedefs.md"
142+
- "Namespace Member Enumerations": "esp/namespace_member_enums.md"
143+
- "Functions": "esp/functions.md"
144+
- "Variables": "esp/variables.md"
145+
- "Macros": "esp/macros.md"
146+
- "Files": "esp/files.md"
147+
- STM-32:
148+
- stm32/index.md
149+
- "Links": "stm/links.md"
150+
- "Classes":
151+
- "Class List": "stm/annotated.md"
152+
- "Class Index": "stm/classes.md"
153+
- "Class Hierarchy": "stm/hierarchy.md"
154+
- "Class Members": "stm/class_members.md"
155+
- "Class Member Functions": "stm/class_member_functions.md"
156+
- "Class Member Variables": "stm/class_member_variables.md"
157+
- "Class Member Typedefs": "stm/class_member_typedefs.md"
158+
- "Class Member Enumerations": "stm/class_member_enums.md"
159+
- "Namespaces":
160+
- "Namespace List": "stm/namespaces.md"
161+
- "Namespace Members": "stm/namespace_members.md"
162+
- "Namespace Member Functions": "stm/namespace_member_functions.md"
163+
- "Namespace Member Variables": "stm/namespace_member_variables.md"
164+
- "Namespace Member Typedefs": "stm/namespace_member_typedefs.md"
165+
- "Namespace Member Enumerations": "stm/namespace_member_enums.md"
166+
- "Functions": "stm/functions.md"
167+
- "Variables": "stm/variables.md"
168+
- "Macros": "stm/macros.md"
169+
- "Files": "stm/files.md"
170+
- Animal:
171+
- animal/index.md
172+
- "Links": "animal/links.md"
173+
- "Classes":
174+
- "Class List": "animal/annotated.md"
175+
- "Class Index": "animal/classes.md"
176+
- "Class Hierarchy": "animal/hierarchy.md"
177+
- "Class Members": "animal/class_members.md"
178+
- "Class Member Functions": "animal/class_member_functions.md"
179+
- "Class Member Variables": "animal/class_member_variables.md"
180+
- "Class Member Typedefs": "animal/class_member_typedefs.md"
181+
- "Class Member Enumerations": "animal/class_member_enums.md"
182+
- "Namespaces":
183+
- "Namespace List": "animal/namespaces.md"
184+
- "Namespace Members": "animal/namespace_members.md"
185+
- "Namespace Member Functions": "animal/namespace_member_functions.md"
186+
- "Namespace Member Variables": "animal/namespace_member_variables.md"
187+
- "Namespace Member Typedefs": "animal/namespace_member_typedefs.md"
188+
- "Namespace Member Enumerations": "animal/namespace_member_enums.md"
189+
- "Functions": "animal/functions.md"
190+
- "Variables": "animal/variables.md"
191+
- "Macros": "animal/macros.md"
192+
- "Files": "animal/files.md"
193+
- Jaculus:
194+
- jaculus/index.md
195+
- "Links": "jaculus/links.md"
196+
- "Classes":
197+
- "Class List": "jaculus/annotated.md"
198+
- "Class Index": "jaculus/classes.md"
199+
- "Class Hierarchy": "jaculus/hierarchy.md"
200+
- "Class Members": "jaculus/class_members.md"
201+
- "Class Member Functions": "jaculus/class_member_functions.md"
202+
- "Class Member Variables": "jaculus/class_member_variables.md"
203+
- "Class Member Typedefs": "jaculus/class_member_typedefs.md"
204+
- "Class Member Enumerations": "jaculus/class_member_enums.md"
205+
- "Namespaces":
206+
- "Namespace List": "jaculus/namespaces.md"
207+
- "Namespace Members": "jaculus/namespace_members.md"
208+
- "Namespace Member Functions": "jaculus/namespace_member_functions.md"
209+
- "Namespace Member Variables": "jaculus/namespace_member_variables.md"
210+
- "Namespace Member Typedefs": "jaculus/namespace_member_typedefs.md"
211+
- "Namespace Member Enumerations": "jaculus/namespace_member_enums.md"
212+
- "Functions": "jaculus/functions.md"
213+
- "Variables": "jaculus/variables.md"
214+
- "Macros": "jaculus/macros.md"
215+
- "Files": "jaculus/files.md"

0 commit comments

Comments
 (0)