Skip to content

Commit 0048e0d

Browse files
JakubAndrysekJakubAndrysek
committed
Update to the new MkDoxy config
1 parent e15df3b commit 0048e0d

File tree

8 files changed

+604
-415
lines changed

8 files changed

+604
-415
lines changed

‎devdeps.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,4 @@ 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

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

0 commit comments

Comments
 (0)