Context
The _spl_create_docs_target and _spl_create_reports_target macros in common.cmake (lines ~483–528) manually construct JSON strings using CMake's list(JOIN ...), string(JSON ...), and escaped quotes. This approach is fragile, hard to read, and difficult to maintain — CMake is not designed for structured data manipulation.
Current State
list(JOIN COMPONENTS_INFO "," _components_info_json)
set(_components_info_json "[${_components_info_json}]")
list(JOIN COMPONENTS_SPHINX_INCLUDE_PATTERNS "\",\"" _components_sphinx_include_patterns_json)
set(_components_sphinx_include_patterns_json "[\"${_components_sphinx_include_patterns_json}\"]")
file(WRITE ${_reports_config_json} "{
\"target\": \"reports\",
\"include_patterns\": ${_components_sphinx_include_patterns_json},
\"reports_output_dir\": \"${_rel_reports_output_dir}\",
\"components_info\": ${_components_info_json}
}")Additionally, the _spl_create_reports_target macro iterates over COMPONENTS_INFO using string(JSON ... GET ...) to extract per-component fields (name, path, reports_output_dir, long_name, has_docs, source_docs_dir) for generating wrapper index pages and toctree content (lines ~538–570).
Proposed Solution
Create a Python script in src/spl_core/ (e.g., generate_sphinx_config.py) that:
- Accepts component info as input (either via CLI args or a simple input file written by CMake)
- Generates the
config.json for docs/reports targets with proper JSON serialization
- Generates the per-component wrapper index files as
.md (using myst-parser directive syntax)
- Generates the coverage fallback stub
The CMake code would then reduce to:
add_custom_command(
OUTPUT ${_reports_config_json}
COMMAND python -m spl_core.generate_sphinx_config
--target reports
--output-dir ${_reports_output_dir}
--project-source-dir ${PROJECT_SOURCE_DIR}
--components-info-file ${_components_info_file}
DEPENDS ${_components_info_file}
)Scope
_spl_create_docs_target macro (lines 483–507)_spl_create_reports_target macro (lines 509–600+)- All
string(JSON ...) and manual JSON string construction
- Per-component wrapper page generation (toctree content)
- Convert remaining generated
.rst files (wrapper pages) to .md using myst-parser directive syntax
Benefits
- Proper JSON handling with Python's
json module (no escaping issues)
- Easier to test (unit tests for the Python script)
- More readable and maintainable
- Consistent with the existing pattern of Python helpers (e.g.,
coverage_to_md.py)
- All generated files use
.md — no more mixed .rst/.md for generated content
Acceptance Criteria
Context
The
_spl_create_docs_targetand_spl_create_reports_targetmacros incommon.cmake(lines ~483–528) manually construct JSON strings using CMake'slist(JOIN ...),string(JSON ...), and escaped quotes. This approach is fragile, hard to read, and difficult to maintain — CMake is not designed for structured data manipulation.Current State
Additionally, the
_spl_create_reports_targetmacro iterates overCOMPONENTS_INFOusingstring(JSON ... GET ...)to extract per-component fields (name,path,reports_output_dir,long_name,has_docs,source_docs_dir) for generating wrapper index pages and toctree content (lines ~538–570).Proposed Solution
Create a Python script in
src/spl_core/(e.g.,generate_sphinx_config.py) that:config.jsonfor docs/reports targets with proper JSON serialization.md(using myst-parser directive syntax)The CMake code would then reduce to:
Scope
_spl_create_docs_targetmacro (lines 483–507)_spl_create_reports_targetmacro (lines 509–600+)string(JSON ...)and manual JSON string construction.rstfiles (wrapper pages) to.mdusing myst-parser directive syntaxBenefits
jsonmodule (no escaping issues)coverage_to_md.py).md— no more mixed.rst/.mdfor generated contentAcceptance Criteria
.md(not.rst)