Skip to content

Commit c012a5c

Browse files
JakubAndrysekJakubAndrysek
authored
Merge pull request #127 from JakubAndrysek/core-update-config
Update to the new MkDoxy config
2 parents e15df3b + 0724cea commit c012a5c

22 files changed

+1836
-489
lines changed

‎.github/workflows/mkdoxy-test-demos.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ jobs:
2424
python -m pip install -e ".[dev]"
2525
sudo apt-get install doxygen
2626
- name: Clone test repo
27-
run: git clone https://github.com/JakubAndrysek/MkDoxy-demo.git demo
27+
run: git clone --branch core-update https://github.com/JakubAndrysek/MkDoxy-demo.git demo
2828
- name: Build docs
2929
run: |
3030
cd demo

‎devdeps.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,5 @@ pre-commit~=3.7.0
77
setuptools~=70.0.0
88
build~=1.2.2
99
twine~=5.1.1
10+
sourcery~=1.34.0
11+
click~=8.1.8

‎mkdocs.yml

Lines changed: 39 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -78,29 +78,56 @@ plugins:
7878
enabled: !ENV [ENABLE_MKDOXY, True]
7979
projects:
8080
mkdoxyApi:
81-
src-dirs: mkdoxy
82-
full-doc: True
83-
template-dir: templates-custom
84-
doxy-cfg-file: demo-projects/animal/Doxyfile
85-
doxy-cfg:
81+
src_dirs: mkdoxy
82+
full_doc: True
83+
template_dir: templates-custom
84+
# doxy_config_file: demo-projects/animal/Doxyfile
85+
doxy_config_dict:
8686
FILE_PATTERNS: "*.py"
8787
EXAMPLE_PATH: ""
8888
RECURSIVE: True
8989
OPTIMIZE_OUTPUT_JAVA: True
9090
JAVADOC_AUTOBRIEF: True
9191
EXTRACT_ALL: True
9292
animal:
93-
src-dirs: demo-projects/animal
94-
full-doc: True
95-
doxy-cfg:
93+
src_dirs: demo-projects/animal
94+
full_doc: True
95+
doxy_config_dict:
9696
FILE_PATTERNS: "*.cpp *.h*"
9797
EXAMPLE_PATH: examples
9898
RECURSIVE: True
99-
save-api: .mkdoxy
100-
full-doc: True
99+
# save_api: .mkdoxy
100+
full_doc: True
101101
debug: False
102-
ignore-errors: False
103-
emojis-enabled: True
102+
ignore_errors: False
103+
104+
# - mkdoxy:
105+
# enabled: !ENV [ENABLE_MKDOXY, True]
106+
# projects:
107+
# mkdoxyApi:
108+
# src-dirs: mkdoxy
109+
# full-doc: True
110+
# template-dir: templates-custom
111+
# doxy-cfg-file: demo-projects/animal/Doxyfile
112+
# doxy-cfg:
113+
# FILE_PATTERNS: "*.py"
114+
# EXAMPLE_PATH: ""
115+
# RECURSIVE: True
116+
# OPTIMIZE_OUTPUT_JAVA: True
117+
# JAVADOC_AUTOBRIEF: True
118+
# EXTRACT_ALL: True
119+
# animal:
120+
# src-dirs: demo-projects/animal
121+
# full-doc: True
122+
# doxy-cfg:
123+
# FILE_PATTERNS: "*.cpp *.h*"
124+
# EXAMPLE_PATH: examples
125+
# RECURSIVE: True
126+
# save-api: .mkdoxy
127+
# full-doc: True
128+
# debug: False
129+
# ignore-errors: False
130+
# emojis-enabled: True
104131

105132
markdown_extensions:
106133
- pymdownx.highlight

‎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/constants.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,3 +168,6 @@ class Visibility(Enum):
168168
PACKAGE = "package"
169169
PROTECTED = "protected"
170170
PRIVATE = "private"
171+
172+
173+
JINJA_EXTENSIONS = (".jinja2", ".j2", ".jinja")

‎mkdoxy/doxy_config.py

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
import logging
2+
from pathlib import Path
3+
4+
from mkdocs.config import Config
5+
from mkdocs.config import config_options as c
6+
7+
log: logging.Logger = logging.getLogger("mkdocs")
8+
9+
config_scheme_legacy = {
10+
"full-doc": "full_doc",
11+
"ignore-errors": "ignore_errors",
12+
"save-api": "custom_api_folder",
13+
"doxygen-bin-path": "doxygen_bin_path",
14+
}
15+
16+
config_project_legacy = {
17+
"src-dirs": "src_dirs",
18+
"full-doc": "full_doc",
19+
"ignore-errors": "ignore_errors",
20+
"doxy-cfg": "doxy_config_dict",
21+
"doxy-cfg-file": "doxy_config_file",
22+
"template-dir": "custom_template_dir",
23+
}
24+
25+
26+
class MkDoxyConfigProject(Config):
27+
"""! Configuration for each project in the MkDoxy configuration file.
28+
@details New type of configuration for each project in the MkDoxy configuration file.
29+
It will replace the old configuration type.
30+
31+
@param src_dirs: (str) Source directories for Doxygen - INPUT
32+
@param full_doc: (bool) Generate full documentation
33+
@param debug: (bool) Debug mode
34+
@param ignore_errors: (bool) Ignore errors
35+
@param doxy_config_dict: (dict) Doxygen additional configuration
36+
@param doxy_config_default: (bool) Use default MkDoxy Doxygen configuration
37+
@param doxy_config_file: (str) Doxygen configuration file
38+
@param doxy_config_file_force: (bool) Do not use default MkDoxy Doxygen configuration, use only Doxygen configuration file
39+
@param custom_template_dir: (str) Custom template directory
40+
"""
41+
42+
src_dirs = c.Type(str)
43+
full_doc = c.Type(bool, default=True)
44+
debug = c.Type(bool, default=False)
45+
ignore_errors = c.Type(bool, default=False)
46+
doxy_config_dict = c.Type(dict, default={})
47+
doxy_config_default = c.Type(bool, default=True)
48+
doxy_config_file = c.Optional(c.Type(Path))
49+
doxy_config_file_force = c.Type(bool, default=False)
50+
custom_template_dir = c.Optional(c.Type(str))
51+
52+
53+
class MkDoxyConfig(Config):
54+
"""! Global configuration for the MkDoxy plugin.
55+
@details New type of global configuration for the MkDoxy plugin. It will replace the old configuration type.
56+
@param projects: (dict) Project configuration - multiple projects
57+
@param full_doc: (bool) Generate full documentation - global (all projects)
58+
@param debug: (bool) Debug mode
59+
@param ignore_errors: (bool) Ignore errors
60+
@param custom_api_folder: (str) Custom API folder for Doxygen and MD output (default in temp folder)
61+
@param doxygen_bin_path: (str) Path to Doxygen binary - default "doxygen"
62+
"""
63+
64+
projects = c.DictOfItems(c.SubConfig(MkDoxyConfigProject), default={}) # project configuration - multiple projects
65+
full_doc = c.Type(bool, default=True) # generate full documentation - global (all projects)
66+
debug = c.Type(bool, default=False) # debug mode
67+
ignore_errors = c.Type(bool, default=False) # ignore errors
68+
custom_api_folder = c.Optional(c.Type(str)) # custom API folder for Doxygen and MD output (default in temp folder)
69+
doxy_config_dict = c.Type(
70+
dict, default={}
71+
) # Doxygen additional configuration - it is overwritten by project config
72+
doxygen_bin_path = c.Type(Path, default=Path("doxygen")) # path to Doxygen binary (default "doxygen"
73+
74+
generate_diagrams = c.Type(bool, default=False) # generate diagrams
75+
generate_diagrams_format = c.Choice(("svg", "png", "jpg", "gif"), default="svg") # diagram format
76+
generate_diagrams_type = c.Choice(("dot", "uml"), default="dot") # diagram type
77+
78+
79+
# def load_config_by_key(key: str, legacy_key: str, config: Config, legacy: list) -> any:
80+
# """! Load the configuration value from the global configuration
81+
# @details Legacy config option is by default None, but if it is not None, it will print a warning and return value.
82+
# @param key: (str) The new configuration key.
83+
# @param legacy_key: (str) The legacy configuration key.
84+
# @param config: (Config) The global configuration object.
85+
# @param legacy: (list) The list of legacy configuration options.
86+
# @return: (Optional[str]) The configuration value.
87+
# """
88+
# if config.get(legacy_key) is not None:
89+
# legacy.append(f"Found legacy configuration options: '{legacy_key}' -> replace with '{key}'")
90+
# return config.get(legacy_key)
91+
# return config.get(key)
92+
#
93+
#
94+
# def process_configuration(config: Config) -> MkDoxyConfig:
95+
# """! Process the configuration for the MkDoxy plugin
96+
# @details Process the configuration for the MkDoxy plugin and validate the configuration.
97+
# It will try to load new configuration, but it will also check for legacy configuration options.
98+
# @param config: (Config) The global configuration object.
99+
# @return: (MkDoxyConfig) The new validated configuration object.
100+
# @throws ConfigurationError: If the configuration is invalid.
101+
# """
102+
# legacy_options = []
103+
# doxy_config = MkDoxyConfig()
104+
# doxy_config.full_doc = load_config_by_key("full_doc", "full-doc", config, legacy_options)
105+
# doxy_config.debug = config.get("debug", False)
106+
# doxy_config.ignore_errors = load_config_by_key("ignore_errors", "ignore-errors", config, legacy_options)
107+
# doxy_config.custom_api_folder = load_config_by_key("custom_api_folder", "save-api", config, legacy_options)
108+
# doxy_config.doxygen_bin_path = load_config_by_key("doxygen_bin_path", "doxygen-bin-path", config, legacy_options)
109+
#
110+
# doxy_config.generate_diagrams = config.get("generate_diagrams")
111+
# doxy_config.generate_diagrams_format = config.get("generate_diagrams_format")
112+
# doxy_config.generate_diagrams_type = config.get("generate_diagrams_type")
113+
#
114+
# # Validate the global configuration
115+
# validate_project_config(doxy_config, legacy_options)
116+
#
117+
# # Validate and load project configuration
118+
# for project_name, project_cfg in config.get("projects", {}).items():
119+
# doxy_config.projects[project_name] = load_project_config(project_cfg, project_name)
120+
#
121+
# return doxy_config
122+
#
123+
#
124+
# def validate_project_config(doxy_cfg: Config, legacy_options: list[str]) -> None:
125+
# """! Validate the project configuration for the MkDoxy plugin
126+
# @details Validate the project configuration for the MkDoxy plugin and check for errors and warnings.
127+
# @param doxy_cfg: (MkDoxyConfig) The project configuration object.
128+
# @param legacy_options: (list) The list of problems.
129+
# @return: None
130+
# @throws ConfigurationError: If the configuration is invalid.
131+
# """
132+
# if legacy_options:
133+
# log.warning("Found some legacy configuration options, please update your configuration!")
134+
# log.warning("Run command 'mkdoxy migrate mkdocs.yaml' to update your configuration to the new format!")
135+
# log.warning("More information in the documentation: https://mkdoxy.kubaandrysek.cz/")
136+
# for problem in legacy_options:
137+
# log.warning(f" -> {problem}")
138+
#
139+
# failed, warnings = doxy_cfg.validate()
140+
#
141+
# for config_name, warning in warnings:
142+
# log.warning(f" -> Config value: '{config_name}'. Warning: {warning}")
143+
#
144+
# for config_name, error in failed:
145+
# log.error(f" -> Config value: '{config_name}'. Error: {error}")
146+
# raise exceptions.ConfigurationError(f"Config value: '{config_name}'. Error: {error}")
147+
#
148+
#
149+
# def load_project_config_by_key(key: str, legacy_key: str, project_cfg: dict, project_name: str, problems: list) -> any:
150+
# """! Load the project configuration value from the project configuration
151+
# @details Legacy project config option is by default None, but if it is not None,
152+
# it will print a warning and return the value.
153+
# @param key: (str) The new project configuration key.
154+
# @param legacy_key: (str) The legacy project configuration key.
155+
# @param project_cfg: (dict) The project configuration object.
156+
# @param project_name: (str) The project name.
157+
# @param problems: (list) The list of problems.
158+
# @return: (Optional[str]) The project configuration value.
159+
# """
160+
# if project_cfg.get(legacy_key) is not None:
161+
# problems.append(
162+
# f"Found legacy configuration options: '{legacy_key}' -> replace with '{key}'"
163+
# f" in project '{project_name}'"
164+
# )
165+
# return project_cfg.get(legacy_key)
166+
# return project_cfg.get(key)
167+
#
168+
#
169+
# def load_project_config(project_cfg: dict, project_name: str) -> MkDoxyConfigProject:
170+
# """! Load the project configuration for the MkDoxy plugin
171+
# @details Load the project configuration for the MkDoxy plugin and validate the configuration.
172+
# @param project_cfg: (dict) The project configuration object.
173+
# @param project_name: (str) The project name.
174+
# @return: (MkDoxyConfigProject) The new validated project configuration object.
175+
# """
176+
# legacy_options = []
177+
# doxy_project_cfg = MkDoxyConfigProject()
178+
# doxy_project_cfg.src_dirs = load_project_config_by_key(
179+
# "src_dirs", "src-dirs", project_cfg, project_name, legacy_options
180+
# )
181+
#
182+
# doxy_project_cfg.full_doc = load_project_config_by_key(
183+
# "full_doc", "full-doc", project_cfg, project_name, legacy_options
184+
# )
185+
# doxy_project_cfg.debug = project_cfg.get("debug", False)
186+
# doxy_project_cfg.ignore_errors = load_project_config_by_key(
187+
# "ignore_errors", "ignore-errors", project_cfg, project_name, legacy_options
188+
# )
189+
# doxy_project_cfg.doxy_config_dict = load_project_config_by_key(
190+
# "doxy_config_dict", "doxy-cfg", project_cfg, project_name, legacy_options
191+
# )
192+
#
193+
# validate_config_file: Optional[str] = load_project_config_by_key(
194+
# "doxy_config_file", "doxy-cfg-file", project_cfg, project_name, legacy_options
195+
# )
196+
# doxy_project_cfg.doxy_config_file = None if validate_config_file is None else Path(validate_config_file)
197+
#
198+
# validate_template_dir: Optional[str] = load_project_config_by_key(
199+
# "custom_template_dir", "template-dir", project_cfg, project_name, legacy_options
200+
# )
201+
# doxy_project_cfg.custom_template_dir = None if validate_template_dir is None else Path(validate_template_dir)
202+
#
203+
# validate_project_config(doxy_project_cfg, legacy_options)
204+
# return doxy_project_cfg

0 commit comments

Comments
 (0)