project-documentation 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,3 @@
1
+ """project-documentation — documentation pipeline for embedded projects."""
2
+
3
+ __version__ = "0.2.0"
@@ -0,0 +1,119 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ build_documentation_pdfs.py — Converts documentation Markdown files and YAML
4
+ requirements to PDF using Pandoc.
5
+
6
+ Usage:
7
+ project-documentation-build-pdfs \\
8
+ --version v1.2.3 \\
9
+ --output-dir docs-pdf \\
10
+ --docs-dirs documentation/architecture documentation/design documentation/theory \\
11
+ --requirements-dir documentation/requirements
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import argparse
17
+ import subprocess
18
+ import sys
19
+ import tempfile
20
+ from pathlib import Path
21
+
22
+ import yaml
23
+
24
+ PANDOC_FLAGS = [
25
+ "--pdf-engine=pdflatex",
26
+ "-V", "geometry:margin=2cm",
27
+ "-V", "fontsize=11pt",
28
+ "--toc",
29
+ "--standalone",
30
+ ]
31
+
32
+
33
+ def _run_pandoc(output_path: Path, *input_paths: Path) -> bool:
34
+ cmd = ["pandoc", *PANDOC_FLAGS, "-o", str(output_path), *[str(p) for p in input_paths]]
35
+ result = subprocess.run(cmd, capture_output=True, text=True)
36
+ if result.returncode != 0:
37
+ print(f"WARNING: pandoc failed for {output_path.name}: {result.stderr.strip()}", file=sys.stderr)
38
+ return False
39
+ print(f"Generated: {output_path}")
40
+ return True
41
+
42
+
43
+ def convert_markdown_dirs(docs_dirs: list[str], version: str, output_dir: Path) -> None:
44
+ for docdir in docs_dirs:
45
+ path = Path(docdir)
46
+ if not path.is_dir():
47
+ continue
48
+ category = path.name
49
+ for md in sorted(path.rglob("*.md")):
50
+ name = md.stem
51
+ out = output_dir / f"e_foc-{category}-{name}-{version}.pdf"
52
+ _run_pandoc(out, md)
53
+
54
+
55
+ def _requirement_to_markdown(req: dict[str, str]) -> str:
56
+ req_id = req.get("id", "").strip()
57
+ title = req.get("title", "").strip()
58
+ shall = req.get("shall", "").strip()
59
+ lines = [f"## {req_id}: {title}", ""]
60
+ if shall:
61
+ lines.append(shall)
62
+ lines.append("")
63
+ return "\n".join(lines)
64
+
65
+
66
+ def convert_requirements(requirements_dir: Path, version: str, output_dir: Path) -> None:
67
+ yaml_files = sorted(requirements_dir.rglob("*.yaml"))
68
+ if not yaml_files:
69
+ print(f"INFO: No YAML files found in {requirements_dir}", file=sys.stderr)
70
+ return
71
+
72
+ with tempfile.TemporaryDirectory() as tmp:
73
+ tmp_mds: list[Path] = []
74
+ for yaml_file in yaml_files:
75
+ with yaml_file.open(encoding="utf-8") as fh:
76
+ items = yaml.safe_load(fh) or []
77
+ if not isinstance(items, list):
78
+ continue
79
+ md_content = "\n".join(_requirement_to_markdown(r) for r in items)
80
+ tmp_md = Path(tmp) / f"{yaml_file.stem}.md"
81
+ tmp_md.write_text(md_content, encoding="utf-8")
82
+ tmp_mds.append(tmp_md)
83
+
84
+ if not tmp_mds:
85
+ print("INFO: No requirements content to convert", file=sys.stderr)
86
+ return
87
+
88
+ out = output_dir / f"e_foc-requirements-{version}.pdf"
89
+ _run_pandoc(out, *tmp_mds)
90
+
91
+
92
+ def main() -> int:
93
+ parser = argparse.ArgumentParser(description="Build documentation PDFs from Markdown and YAML requirements")
94
+ parser.add_argument("--version", required=True, help="Release version tag (e.g. v1.2.3)")
95
+ parser.add_argument("--output-dir", default="docs-pdf", help="Output directory for PDFs")
96
+ parser.add_argument(
97
+ "--docs-dirs",
98
+ nargs="+",
99
+ default=["documentation/architecture", "documentation/design", "documentation/theory"],
100
+ help="Space-separated list of documentation directories to convert",
101
+ )
102
+ parser.add_argument(
103
+ "--requirements-dir",
104
+ default="documentation/requirements",
105
+ help="Directory containing YAML requirement files",
106
+ )
107
+ args = parser.parse_args()
108
+
109
+ output_dir = Path(args.output_dir)
110
+ output_dir.mkdir(parents=True, exist_ok=True)
111
+
112
+ convert_markdown_dirs(args.docs_dirs, args.version, output_dir)
113
+ convert_requirements(Path(args.requirements_dir), args.version, output_dir)
114
+
115
+ return 0
116
+
117
+
118
+ if __name__ == "__main__":
119
+ sys.exit(main())
@@ -0,0 +1,62 @@
1
+ #!/usr/bin/env python3
2
+ """Generate requirements PDF from YAML files using a template."""
3
+
4
+ import argparse
5
+ import subprocess
6
+ from pathlib import Path
7
+
8
+ import yaml
9
+
10
+
11
+ def main() -> None:
12
+ parser = argparse.ArgumentParser()
13
+ parser.add_argument("--requirements-dir", required=True, type=Path)
14
+ parser.add_argument("--template", required=True, type=Path)
15
+ parser.add_argument("--output", required=True, type=Path)
16
+ args = parser.parse_args()
17
+
18
+ # Start with template content
19
+ markdown = args.template.read_text()
20
+
21
+ # Group requirements by subdirectory
22
+ yaml_files = sorted(args.requirements_dir.glob("**/*.yaml"))
23
+ sections: dict[str, list[dict[str, str]]] = {}
24
+
25
+ for yaml_file in yaml_files:
26
+ section = yaml_file.parent.name.replace("-", " ").replace("_", " ").title()
27
+ content = yaml.safe_load(yaml_file.read_text())
28
+
29
+ if content is None:
30
+ continue
31
+
32
+ if section not in sections:
33
+ sections[section] = []
34
+ sections[section].extend(content)
35
+
36
+ # Generate markdown for each section
37
+ for section, requirements in sorted(sections.items()):
38
+ markdown += f"\n## {section}\n\n"
39
+
40
+ for req in requirements:
41
+ markdown += f"### {req['id']}: {req['title']}\n\n"
42
+ markdown += f"{req['shall']}\n\n"
43
+
44
+ # Write intermediate markdown
45
+ md_path = args.output.with_suffix(".md")
46
+ md_path.parent.mkdir(parents=True, exist_ok=True)
47
+ md_path.write_text(markdown)
48
+
49
+ # Convert to PDF with pandoc
50
+ args.output.parent.mkdir(parents=True, exist_ok=True)
51
+ subprocess.run([
52
+ "pandoc", str(md_path),
53
+ "-o", str(args.output),
54
+ "--toc",
55
+ "-V", "geometry:margin=1in"
56
+ ], check=True)
57
+
58
+ print(f"✓ Generated {args.output}")
59
+
60
+
61
+ if __name__ == "__main__":
62
+ main()
@@ -0,0 +1,278 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ generate-traceability-matrix.py
4
+
5
+ Generates a requirements-vs-SIL traceability matrix in Markdown.
6
+
7
+ Usage:
8
+ python3 generate-traceability-matrix.py \
9
+ --requirements-dir documentation/requirements \
10
+ --features-dir integration_tests/software_in_the_loop/features \
11
+ [--junit-xml sil-test-report.xml] \
12
+ --output traceability-matrix.md
13
+
14
+ The requirements are loaded from all *.yaml files under --requirements-dir.
15
+ Each YAML file must be a YAML list whose items have at minimum:
16
+ - id: REQ-FOC-002
17
+ title: Independent Id and Iq current control
18
+ shall: >
19
+ ...
20
+
21
+ Feature files under --features-dir are scanned for lines matching
22
+ # REQ-XXX-NNN[, REQ-YYY-NNN ...]
23
+ appearing immediately before a "Scenario:" line. Each such tag maps the
24
+ scenario to the requirement.
25
+
26
+ If --junit-xml is supplied the script parses it to determine whether each
27
+ mapped scenario passed or failed, and adds a status column to the table.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ import argparse
33
+ import re
34
+ import sys
35
+ import xml.etree.ElementTree as ET
36
+ from pathlib import Path
37
+
38
+ import yaml # PyYAML — available in the CI environment via pip
39
+
40
+ # ── Data loading ──────────────────────────────────────────────────────────────
41
+
42
+ def load_requirements(requirements_dir: Path) -> dict[str, dict[str, str]]:
43
+ """Return {req_id: {id, title, shall, domain}} for all YAML files."""
44
+ reqs: dict[str, dict[str, str]] = {}
45
+ for yaml_file in sorted(requirements_dir.rglob("*.yaml")):
46
+ domain = yaml_file.stem
47
+ with yaml_file.open(encoding="utf-8") as fh:
48
+ items = yaml.safe_load(fh) or []
49
+ if not isinstance(items, list):
50
+ continue
51
+ for item in items:
52
+ req_id = item.get("id", "").strip()
53
+ if req_id:
54
+ reqs[req_id] = {
55
+ "id": req_id,
56
+ "title": item.get("title", ""),
57
+ "shall": item.get("shall", "").strip().replace("\n", " "),
58
+ "domain": domain,
59
+ }
60
+ return reqs
61
+
62
+
63
+ _REQ_TAG_RE = re.compile(r"REQ-[A-Z]+-\d+")
64
+ _SCENARIO_RE = re.compile(r"^\s*Scenario(?:\s+Outline)?:\s*(.+)", re.IGNORECASE)
65
+
66
+
67
+ def load_feature_mapping(features_dir: Path) -> dict[str, list[str]]:
68
+ """Return {req_id: [scenario_name, ...]} by scanning feature files."""
69
+ mapping: dict[str, list[str]] = {}
70
+ for feature_file in sorted(features_dir.glob("*.feature")):
71
+ lines = feature_file.read_text(encoding="utf-8").splitlines()
72
+ pending_reqs: list[str] = []
73
+ for line in lines:
74
+ tag_matches = _REQ_TAG_RE.findall(line)
75
+ if tag_matches:
76
+ # Comments may carry multiple IDs; accumulate until Scenario:
77
+ pending_reqs.extend(tag_matches)
78
+ continue
79
+ scenario_match = _SCENARIO_RE.match(line)
80
+ if scenario_match and pending_reqs:
81
+ scenario_name = scenario_match.group(1).strip()
82
+ for req_id in pending_reqs:
83
+ mapping.setdefault(req_id, []).append(scenario_name)
84
+ pending_reqs = []
85
+ elif not line.strip().startswith("#") and line.strip():
86
+ # Non-comment, non-empty, non-scenario line clears pending tags
87
+ pending_reqs = []
88
+ return mapping
89
+
90
+
91
+ def load_junit_results(junit_xml: Path) -> dict[str, str]:
92
+ """Return {scenario_name: 'pass'|'fail'|'skip'} from a JUnit XML file."""
93
+ if not junit_xml.exists():
94
+ return {}
95
+ tree = ET.parse(junit_xml)
96
+ root = tree.getroot()
97
+ results: dict[str, str] = {}
98
+ # Support both <testsuite> and <testsuites> as root element
99
+ test_cases = root.iter("testcase")
100
+ for tc in test_cases:
101
+ name = tc.get("name", "").strip()
102
+ if not name:
103
+ continue
104
+ if tc.find("failure") is not None or tc.find("error") is not None:
105
+ status = "fail"
106
+ elif tc.find("skipped") is not None:
107
+ status = "skip"
108
+ else:
109
+ status = "pass"
110
+ results[name] = status
111
+ return results
112
+
113
+
114
+ # ── Matrix generation ─────────────────────────────────────────────────────────
115
+
116
+ _STATUS_ICON = {
117
+ "pass": "PASS",
118
+ "fail": "FAIL",
119
+ "skip": "SKIP",
120
+ }
121
+
122
+
123
+ def _scenario_status(scenarios: list[str], junit: dict[str, str]) -> str:
124
+ """Aggregate all scenario statuses for a requirement."""
125
+ if not junit:
126
+ return "—"
127
+ statuses = {junit.get(s, "unknown") for s in scenarios}
128
+ if "fail" in statuses:
129
+ return f"{_STATUS_ICON['fail']}"
130
+ if "unknown" in statuses:
131
+ return "PARTIAL"
132
+ if "skip" in statuses and "pass" not in statuses:
133
+ return f"{_STATUS_ICON['skip']}"
134
+ return f"{_STATUS_ICON['pass']}"
135
+
136
+
137
+ def generate_matrix(
138
+ reqs: dict[str, dict[str, str]],
139
+ feature_map: dict[str, list[str]],
140
+ junit: dict[str, str],
141
+ ) -> str:
142
+ """Produce the full Markdown traceability matrix document."""
143
+ include_status = bool(junit)
144
+
145
+ lines: list[str] = [
146
+ "# Requirements Traceability Matrix",
147
+ "",
148
+ "This document maps every requirement to the SIL scenarios that verify it.",
149
+ "",
150
+ ]
151
+
152
+ # Group by domain
153
+ domains: dict[str, list[dict[str, str]]] = {}
154
+ for req in reqs.values():
155
+ domains.setdefault(req["domain"], []).append(req)
156
+
157
+ uncovered: list[str] = []
158
+
159
+ for domain, domain_reqs in sorted(domains.items()):
160
+ domain_title = domain.replace("-", " ").title()
161
+ lines += [f"## {domain_title}", ""]
162
+
163
+ header = "| ID | Title | Scenarios |"
164
+ sep = "|---|---|---|"
165
+ if include_status:
166
+ header = "| ID | Title | Scenarios | Status |"
167
+ sep = "|---|---|---|---|"
168
+
169
+ lines += [header, sep]
170
+
171
+ for req in sorted(domain_reqs, key=lambda r: r["id"]):
172
+ req_id = req["id"]
173
+ title = req["title"]
174
+ scenarios = feature_map.get(req_id, [])
175
+ if not scenarios:
176
+ uncovered.append(req_id)
177
+ scenario_text = "_not covered_"
178
+ else:
179
+ scenario_text = "<br>".join(f"`{s}`" for s in scenarios)
180
+
181
+ if include_status:
182
+ status = _scenario_status(scenarios, junit)
183
+ lines.append(f"| `{req_id}` | {title} | {scenario_text} | {status} |")
184
+ else:
185
+ lines.append(f"| `{req_id}` | {title} | {scenario_text} |")
186
+
187
+ lines.append("")
188
+
189
+ # Uncovered summary
190
+ if uncovered:
191
+ lines += [
192
+ "## Uncovered Requirements",
193
+ "",
194
+ "The following requirements have no scenario tagged in the feature files:",
195
+ "",
196
+ ]
197
+ for req_id in sorted(uncovered):
198
+ lines.append(f"- `{req_id}` — {reqs[req_id]['title']}")
199
+ lines.append("")
200
+
201
+ # Coverage statistics
202
+ total = len(reqs)
203
+ covered = total - len(uncovered)
204
+ pct = int(100 * covered / total) if total else 0
205
+ lines += [
206
+ "## Coverage Summary",
207
+ "",
208
+ f"- **Total requirements**: {total}",
209
+ f"- **Covered by scenarios**: {covered} ({pct}%)",
210
+ f"- **Not covered**: {len(uncovered)}",
211
+ "",
212
+ ]
213
+
214
+ return "\n".join(lines)
215
+
216
+
217
+ # ── Entry point ───────────────────────────────────────────────────────────────
218
+
219
+ def main() -> int:
220
+ parser = argparse.ArgumentParser(description="Generate requirements traceability matrix")
221
+ parser.add_argument(
222
+ "--requirements-dir",
223
+ default="documentation/requirements",
224
+ help="Directory containing *.yaml requirement files (default: documentation/requirements)",
225
+ )
226
+ parser.add_argument(
227
+ "--features-dir",
228
+ default="integration_tests/software_in_the_loop/features",
229
+ help="Directory containing *.feature scenario files",
230
+ )
231
+ parser.add_argument(
232
+ "--junit-xml",
233
+ default=None,
234
+ help="Path to JUnit XML from SIL test run (optional)",
235
+ )
236
+ parser.add_argument(
237
+ "--output",
238
+ default="traceability-matrix.md",
239
+ help="Output Markdown file path (default: traceability-matrix.md)",
240
+ )
241
+ args = parser.parse_args()
242
+
243
+ req_dir = Path(args.requirements_dir)
244
+ feat_dir = Path(args.features_dir)
245
+
246
+ if not req_dir.is_dir():
247
+ print(f"ERROR: requirements directory not found: {req_dir}", file=sys.stderr)
248
+ return 1
249
+ if not feat_dir.is_dir():
250
+ print(f"ERROR: features directory not found: {feat_dir}", file=sys.stderr)
251
+ return 1
252
+
253
+ reqs = load_requirements(req_dir)
254
+ if not reqs:
255
+ print("ERROR: no requirements loaded — check YAML files", file=sys.stderr)
256
+ return 1
257
+
258
+ feature_map = load_feature_mapping(feat_dir)
259
+
260
+ junit: dict[str, str] = {}
261
+ if args.junit_xml:
262
+ junit_path = Path(args.junit_xml)
263
+ if not junit_path.exists():
264
+ print(f"WARNING: JUnit XML not found: {junit_path} — status column omitted", file=sys.stderr)
265
+ else:
266
+ junit = load_junit_results(junit_path)
267
+
268
+ matrix_md = generate_matrix(reqs, feature_map, junit)
269
+
270
+ output_path = Path(args.output)
271
+ output_path.parent.mkdir(parents=True, exist_ok=True)
272
+ output_path.write_text(matrix_md, encoding="utf-8")
273
+ print(f"Traceability matrix written to: {output_path}")
274
+ return 0
275
+
276
+
277
+ if __name__ == "__main__":
278
+ sys.exit(main())
@@ -0,0 +1,252 @@
1
+ #!/usr/bin/env python3
2
+ """Validate markdown documentation files against architecture and design templates."""
3
+
4
+ import argparse
5
+ import re
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ import yaml
10
+
11
+ ARCHITECTURE_REQUIRED_SECTIONS = [
12
+ "Assumptions & Constraints",
13
+ "System Overview",
14
+ "Component Decomposition",
15
+ "Interfaces & Contracts",
16
+ ]
17
+
18
+ DESIGN_REQUIRED_SECTIONS = [
19
+ "Responsibilities",
20
+ "Component Details",
21
+ "Interfaces",
22
+ ]
23
+
24
+ THEORY_REQUIRED_SECTIONS = [
25
+ "Overview",
26
+ "Mathematical Foundation",
27
+ "Numerical Properties",
28
+ ]
29
+
30
+ REQUIRED_FRONTMATTER_FIELDS = ["title", "type", "status", "version", "component"]
31
+
32
+ FORBIDDEN_CODE_LANGUAGES = {
33
+ "cpp", "c", "c++", "cxx",
34
+ "python", "py",
35
+ "java",
36
+ "javascript", "js",
37
+ "typescript", "ts",
38
+ "rust",
39
+ "go",
40
+ "bash", "sh", "shell",
41
+ "cmake",
42
+ "makefile",
43
+ }
44
+
45
+
46
+ def parse_frontmatter(text: str, relative_path: Path) -> tuple[dict[str, object] | None, list[str]]:
47
+ """Parse YAML frontmatter from a markdown document.
48
+
49
+ Returns (parsed_dict_or_None, list_of_errors).
50
+ """
51
+ errors = []
52
+ if not text.startswith("---"):
53
+ errors.append("missing YAML frontmatter (document must start with ---)")
54
+ return None, errors
55
+
56
+ end = text.find("\n---", 3)
57
+ if end == -1:
58
+ errors.append("unclosed YAML frontmatter (no closing ---)")
59
+ return None, errors
60
+
61
+ raw_yaml = text[3:end].strip()
62
+ try:
63
+ data = yaml.safe_load(raw_yaml)
64
+ except yaml.YAMLError as exc:
65
+ errors.append(f"YAML parse error in frontmatter: {exc}")
66
+ return None, errors
67
+
68
+ if not isinstance(data, dict):
69
+ errors.append("frontmatter is not a YAML mapping")
70
+ return None, errors
71
+
72
+ return data, errors
73
+
74
+
75
+ def check_required_fields(frontmatter: dict[str, object]) -> list[str]:
76
+ """Return a list of error messages for missing required frontmatter fields."""
77
+ errors = []
78
+ for field in REQUIRED_FRONTMATTER_FIELDS:
79
+ if field not in frontmatter or frontmatter[field] is None:
80
+ errors.append(f"missing required frontmatter field: '{field}'")
81
+ return errors
82
+
83
+
84
+ def check_required_sections(text: str, required_sections: list[str]) -> list[str]:
85
+ """Return error messages for required H2 sections that are absent."""
86
+ errors = []
87
+ for section in required_sections:
88
+ pattern = re.compile(r"^## " + re.escape(section) + r"(\s|$)", re.MULTILINE)
89
+ if not pattern.search(text):
90
+ errors.append(f"missing required section: '## {section}'")
91
+ return errors
92
+
93
+
94
+ def check_implementation_blindness(text: str, doc_type: str = "design") -> list[str]:
95
+ """Scan fenced code blocks and report any that use forbidden programming languages."""
96
+ errors = []
97
+ fence_pattern = re.compile(r"^```(\w*)", re.MULTILINE)
98
+ for match in fence_pattern.finditer(text):
99
+ lang = match.group(1).strip().lower()
100
+ if lang in FORBIDDEN_CODE_LANGUAGES:
101
+ line_number = text[: match.start()].count("\n") + 1
102
+ errors.append(
103
+ f"forbidden code block language '{lang}' at line {line_number} "
104
+ f"({doc_type} documents must not contain programming-language code blocks)"
105
+ )
106
+ return errors
107
+
108
+
109
+ def check_no_image_references(text: str) -> list[str]:
110
+ """Check that no external image references (![alt](src)) are used.
111
+
112
+ All visuals must be Mermaid code blocks or ASCII art.
113
+ """
114
+ errors = []
115
+ image_pattern = re.compile(r"!\[([^\]]*)\]\(([^)]+)\)")
116
+ inline_code_pattern = re.compile(r"`[^`]*`")
117
+ for line_num, line in enumerate(text.splitlines(), 1):
118
+ # Strip inline code spans first to avoid false-positives on documented examples
119
+ line_without_code = inline_code_pattern.sub("", line)
120
+ if image_pattern.search(line_without_code):
121
+ errors.append(
122
+ f"line {line_num}: external image reference not allowed "
123
+ "— use a Mermaid code block or ASCII art instead"
124
+ )
125
+ return errors
126
+
127
+
128
+ def is_template_file(path: Path, documents_dir: Path) -> bool:
129
+ """Return True if the file is a template (skipped during validation)."""
130
+ try:
131
+ parts = path.relative_to(documents_dir).parts
132
+ except ValueError:
133
+ return False
134
+ return len(parts) >= 2 and parts[-2] == "templates" and path.name in (
135
+ "architecture.md",
136
+ "design.md",
137
+ "theory.md",
138
+ )
139
+
140
+
141
+ def validate_file(
142
+ md_file: Path,
143
+ documents_dir: Path,
144
+ doc_type_filter: str,
145
+ ) -> tuple[list[str], list[str]]:
146
+ """Validate a single markdown file.
147
+
148
+ Returns (errors, warnings).
149
+ """
150
+ errors: list[str] = []
151
+ warnings: list[str] = []
152
+
153
+ text = md_file.read_text(encoding="utf-8")
154
+ if not text.strip():
155
+ warnings.append("file is empty")
156
+ return errors, warnings
157
+
158
+ frontmatter, fm_errors = parse_frontmatter(text, md_file)
159
+ if frontmatter is None:
160
+ if doc_type_filter == "all":
161
+ # When scanning all types, warn about unmanaged files so they are visible.
162
+ warnings.extend(fm_errors)
163
+ # When filtering by a specific type, skip silently: unmanaged files (no frontmatter)
164
+ # do not belong to any managed type and must not pollute filtered CI runs.
165
+ return errors, warnings
166
+ errors.extend(fm_errors)
167
+
168
+ errors.extend(check_required_fields(frontmatter))
169
+
170
+ doc_type = str(frontmatter.get("type", "")).lower()
171
+
172
+ if doc_type_filter != "all" and doc_type != doc_type_filter:
173
+ # Not the type we are filtering for — skip silently.
174
+ return [], []
175
+
176
+ if doc_type == "architecture":
177
+ errors.extend(check_required_sections(text, ARCHITECTURE_REQUIRED_SECTIONS))
178
+ errors.extend(check_implementation_blindness(text, "architecture"))
179
+ errors.extend(check_no_image_references(text))
180
+ elif doc_type == "design":
181
+ errors.extend(check_required_sections(text, DESIGN_REQUIRED_SECTIONS))
182
+ errors.extend(check_implementation_blindness(text, "design"))
183
+ errors.extend(check_no_image_references(text))
184
+ elif doc_type == "theory":
185
+ errors.extend(check_required_sections(text, THEORY_REQUIRED_SECTIONS))
186
+ # Image references are allowed in theory documents (generated plots from documentation/tools/)
187
+ else:
188
+ warnings.append(f"unknown document type '{doc_type}' — skipped type-specific checks")
189
+
190
+ return errors, warnings
191
+
192
+
193
+ def main() -> int:
194
+ parser = argparse.ArgumentParser(
195
+ description="Validate markdown documentation against architecture and design templates."
196
+ )
197
+ parser.add_argument(
198
+ "--documents-dir",
199
+ required=True,
200
+ type=Path,
201
+ help="Directory to search for markdown documentation files.",
202
+ )
203
+ parser.add_argument(
204
+ "--doc-type",
205
+ default="all",
206
+ choices=["architecture", "design", "theory", "all"],
207
+ help="Filter validation to a specific document type (default: all).",
208
+ )
209
+ args = parser.parse_args()
210
+
211
+ documents_dir: Path = args.documents_dir
212
+ if not documents_dir.is_dir():
213
+ print(f"✗ --documents-dir '{documents_dir}' is not a directory", file=sys.stderr)
214
+ return 1
215
+
216
+ md_files = sorted(documents_dir.rglob("*.md"))
217
+ failed = False
218
+
219
+ for md_file in md_files:
220
+ if is_template_file(md_file, documents_dir):
221
+ continue
222
+
223
+ relative_path = md_file.relative_to(documents_dir)
224
+ errors, warnings = validate_file(md_file, documents_dir, args.doc_type)
225
+
226
+ for warning in warnings:
227
+ print(f"⚠ {relative_path}: {warning}")
228
+
229
+ if errors:
230
+ for error in errors:
231
+ print(f"✗ {relative_path}: {error}")
232
+ failed = True
233
+ elif not warnings:
234
+ # Only print ✓ when the file was actually checked (not skipped).
235
+ # A file is skipped when validate_file returns ([], []) due to type mismatch.
236
+ pass
237
+
238
+ if not errors and not warnings:
239
+ # Determine whether we actually validated this file or skipped it.
240
+ text = md_file.read_text(encoding="utf-8")
241
+ if text.strip():
242
+ fm, _ = parse_frontmatter(text, relative_path)
243
+ if fm is not None:
244
+ doc_type = str(fm.get("type", "")).lower()
245
+ if args.doc_type == "all" or doc_type == args.doc_type:
246
+ print(f"✓ {relative_path}")
247
+
248
+ return 1 if failed else 0
249
+
250
+
251
+ if __name__ == "__main__":
252
+ sys.exit(main())
@@ -0,0 +1,42 @@
1
+ #!/usr/bin/env python3
2
+ """Validate YAML requirement files against a JSON schema."""
3
+
4
+ import argparse
5
+ import json
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ import yaml
10
+ from jsonschema import ValidationError, validate
11
+
12
+
13
+ def main() -> int:
14
+ parser = argparse.ArgumentParser()
15
+ parser.add_argument("--schema", required=True, type=Path)
16
+ parser.add_argument("--requirements-dir", required=True, type=Path)
17
+ args = parser.parse_args()
18
+
19
+ schema = json.loads(args.schema.read_text())
20
+ yaml_files = sorted(args.requirements_dir.glob("**/*.yaml"))
21
+ failed = False
22
+
23
+ for yaml_file in yaml_files:
24
+ relative_path = yaml_file.relative_to(args.requirements_dir)
25
+ content = yaml.safe_load(yaml_file.read_text())
26
+
27
+ if content is None:
28
+ print(f"⚠ {relative_path} (empty)")
29
+ continue
30
+
31
+ try:
32
+ validate(content, schema)
33
+ print(f"✓ {relative_path}")
34
+ except ValidationError as e:
35
+ print(f"✗ {relative_path}: {e.message}")
36
+ failed = True
37
+
38
+ return 1 if failed else 0
39
+
40
+
41
+ if __name__ == "__main__":
42
+ sys.exit(main())
@@ -0,0 +1,139 @@
1
+ Metadata-Version: 2.4
2
+ Name: project-documentation
3
+ Version: 0.2.0
4
+ Summary: Documentation pipeline for embedded projects: validates requirements and design documents, generates PDFs, and produces a traceability matrix.
5
+ Project-URL: Homepage, https://github.com/embedded-pro/project-documentation
6
+ Project-URL: Documentation, https://github.com/embedded-pro/project-documentation/tree/main/docs
7
+ Project-URL: Issues, https://github.com/embedded-pro/project-documentation/issues
8
+ Project-URL: Changelog, https://github.com/embedded-pro/project-documentation/blob/main/CHANGELOG.md
9
+ Author: project-documentation contributors
10
+ License: Apache-2.0
11
+ License-File: LICENSE
12
+ Keywords: ci,documentation,embedded,github-action,pdf,requirements,traceability,validation
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: License :: OSI Approved :: Apache Software License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Topic :: Software Development :: Documentation
22
+ Classifier: Topic :: Software Development :: Quality Assurance
23
+ Requires-Python: >=3.11
24
+ Requires-Dist: jsonschema>=4.0
25
+ Requires-Dist: pyyaml>=6.0
26
+ Provides-Extra: dev
27
+ Requires-Dist: mypy>=1.8; extra == 'dev'
28
+ Requires-Dist: pytest-cov>=4.1; extra == 'dev'
29
+ Requires-Dist: pytest>=7.4; extra == 'dev'
30
+ Requires-Dist: ruff>=0.5; extra == 'dev'
31
+ Requires-Dist: types-jsonschema>=4.0; extra == 'dev'
32
+ Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
33
+ Description-Content-Type: text/markdown
34
+
35
+ # project-documentation
36
+
37
+ [![CI](https://github.com/embedded-pro/project-documentation/actions/workflows/ci.yml/badge.svg)](https://github.com/embedded-pro/project-documentation/actions/workflows/ci.yml)
38
+ [![PyPI](https://img.shields.io/pypi/v/project-documentation)](https://pypi.org/project/project-documentation/)
39
+ [![Python](https://img.shields.io/pypi/pyversions/project-documentation)](https://pypi.org/project/project-documentation/)
40
+ [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
41
+
42
+ > Documentation pipeline for embedded projects — CI-friendly, framework-agnostic.
43
+
44
+ `project-documentation` is a GitHub composite action and Python package that covers the full documentation lifecycle for embedded software projects:
45
+
46
+ - **Validate requirements** — check YAML requirement files against a JSON schema
47
+ - **Validate documents** — enforce frontmatter fields and required sections in Markdown architecture/design/theory documents
48
+ - **Generate requirements PDF** — render YAML requirements to a versioned PDF via a Markdown template
49
+ - **Build documentation PDFs** — convert Markdown documentation directories and YAML requirements to PDFs using Pandoc
50
+ - **Traceability matrix** — map requirements to Gherkin scenarios (with optional JUnit pass/fail status), output Markdown and optionally PDF
51
+
52
+ ## ✨ Features
53
+
54
+ | Capability | Description |
55
+ |---|---|
56
+ | Requirements validation | JSON schema validation for YAML requirement files |
57
+ | Document validation | Frontmatter fields, required H2 sections, no code blocks in design docs |
58
+ | Requirements PDF | Template-driven PDF from YAML requirements |
59
+ | Documentation PDFs | Per-directory Markdown → PDF + combined requirements PDF |
60
+ | Traceability matrix | Requirements ↔ scenarios mapping with coverage statistics |
61
+ | PR comment | Idempotent PR comments (traceability matrix) |
62
+ | GitHub Action | Composite action with feature flags for each capability |
63
+
64
+ ## 🚀 Quickstart
65
+
66
+ ### 1. Install
67
+
68
+ ```
69
+ pip install project-documentation
70
+ ```
71
+
72
+ ### 2. Use in GitHub Actions
73
+
74
+ ```yaml
75
+ - uses: embedded-pro/project-documentation@v0
76
+ with:
77
+ run-validate-requirements: 'true'
78
+ run-validate-documents: 'true'
79
+ run-generate-requirements-pdf: 'true'
80
+ run-build-documentation-pdfs: 'true'
81
+ run-traceability-matrix: 'true'
82
+ version: ${{ github.ref_name }}
83
+ ```
84
+
85
+ See [docs/usage.md](docs/usage.md) for the full input/output reference.
86
+
87
+ ### 3. Run from the command line
88
+
89
+ ```bash
90
+ # Validate requirements against a JSON schema
91
+ project-documentation-validate-requirements \
92
+ --schema documentation/tools/requirement.schema.json \
93
+ --requirements-dir documentation/requirements
94
+
95
+ # Validate Markdown documentation
96
+ project-documentation-validate-documents \
97
+ --documents-dir documentation \
98
+ --doc-type architecture
99
+
100
+ # Generate requirements PDF
101
+ project-documentation-generate-requirements-pdf \
102
+ --requirements-dir documentation/requirements \
103
+ --template documentation/templates/requirements.md \
104
+ --output documentation/output/requirements.pdf
105
+
106
+ # Build all documentation PDFs
107
+ project-documentation-build-pdfs \
108
+ --version v1.2.3 \
109
+ --output-dir docs-pdf \
110
+ --docs-dirs documentation/architecture documentation/design documentation/theory \
111
+ --requirements-dir documentation/requirements
112
+
113
+ # Generate traceability matrix
114
+ project-documentation-traceability-matrix \
115
+ --requirements-dir documentation/requirements \
116
+ --features-dir integration_tests/software_in_the_loop/features \
117
+ --output docs-pdf/traceability-matrix.md \
118
+ --junit-xml sil-test-report.xml
119
+ ```
120
+
121
+ ## 📚 Documentation
122
+
123
+ | File | Contents |
124
+ |---|---|
125
+ | [docs/usage.md](docs/usage.md) | CLI flags, action inputs/outputs, examples |
126
+ | [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, testing, release process |
127
+ | [CHANGELOG.md](CHANGELOG.md) | Version history |
128
+
129
+ ## ⚠️ System dependencies
130
+
131
+ The PDF-generating capabilities require:
132
+ - `pandoc` — document converter
133
+ - `pdflatex` (via `texlive-latex-recommended`, `texlive-latex-extra`, `texlive-fonts-recommended`)
134
+
135
+ The GitHub Action installs these automatically when any PDF feature flag is enabled.
136
+
137
+ ## 📄 License
138
+
139
+ Apache-2.0 — see [LICENSE](LICENSE).
@@ -0,0 +1,11 @@
1
+ project_documentation/__init__.py,sha256=-MPx-U6pX2fGTLtJ69SmiDOC-Y9BBxJBocXr6glDg4E,101
2
+ project_documentation/build_documentation_pdfs.py,sha256=SOagkCV5J_wLvkbI2NWZNTjzI1ld0FBHVmDcxw0PHVo,3922
3
+ project_documentation/generate_requirements_pdf.py,sha256=0nSxJmW_W48RggjNMQ8LM-vxE9JJElQCxRydu_jD8jM,1809
4
+ project_documentation/generate_traceability_matrix.py,sha256=avIy_wMeFHAhtXclz1KYVcUSo9JRmogIWF4cTTM5C-c,9741
5
+ project_documentation/validate_documents.py,sha256=7G2wJ8nqI-yPH2vzlCdPNCJg7Y5EImDQWO24WJE2vDc,8499
6
+ project_documentation/validate_requirements.py,sha256=BgvyBCZc-ZZlEfplDJfnjkesBA8t0bjBrC9cStbFB1Y,1122
7
+ project_documentation-0.2.0.dist-info/METADATA,sha256=tsOd81l9NP1b7diRPdlPHY50GrfZdyrWgJeb_oiqdK0,5869
8
+ project_documentation-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
9
+ project_documentation-0.2.0.dist-info/entry_points.txt,sha256=f-mOVwRNIY4BDlBxFkpRqua-P_bf3tW2hhob1yGZ8Qw,492
10
+ project_documentation-0.2.0.dist-info/licenses/LICENSE,sha256=_E12Vzzxd03cVo5TTNMPHv5zpskk2O1uuq27OR_OQe8,3909
11
+ project_documentation-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.29.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,6 @@
1
+ [console_scripts]
2
+ project-documentation-build-pdfs = project_documentation.build_documentation_pdfs:main
3
+ project-documentation-generate-requirements-pdf = project_documentation.generate_requirements_pdf:main
4
+ project-documentation-traceability-matrix = project_documentation.generate_traceability_matrix:main
5
+ project-documentation-validate-documents = project_documentation.validate_documents:main
6
+ project-documentation-validate-requirements = project_documentation.validate_requirements:main
@@ -0,0 +1,90 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity.
18
+
19
+ "You" (or "Your") shall mean an individual or Legal Entity
20
+ exercising permissions granted by this License.
21
+
22
+ "Source" form shall mean the preferred form for making modifications,
23
+ including but not limited to software source code, documentation
24
+ source, and configuration files.
25
+
26
+ "Object" form shall mean any form resulting from mechanical
27
+ transformation or translation of a Source form, including but
28
+ not limited to compiled object code, generated documentation,
29
+ and conversions to other media types.
30
+
31
+ "Work" shall mean the work of authorship made available under
32
+ the License.
33
+
34
+ "Derivative Works" shall mean any work that is based on the Work.
35
+
36
+ "Contribution" shall mean any work of authorship submitted to the Licensor.
37
+
38
+ "Contributor" shall mean Licensor and any Legal Entity on behalf
39
+ of whom a Contribution has been received by the Licensor.
40
+
41
+ 2. Grant of Copyright License. Subject to the terms and conditions of
42
+ this License, each Contributor hereby grants to You a perpetual,
43
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
44
+ copyright license to reproduce, prepare Derivative Works of,
45
+ publicly display, publicly perform, sublicense, and distribute the
46
+ Work and such Derivative Works in Source or Object form.
47
+
48
+ 3. Grant of Patent License. Subject to the terms and conditions of
49
+ this License, each Contributor hereby grants to You a perpetual,
50
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
51
+ patent license to make, have made, use, offer to sell, sell,
52
+ import, and otherwise transfer the Work.
53
+
54
+ 4. Redistribution. You may reproduce and distribute copies of the
55
+ Work or Derivative Works thereof in any medium, with or without
56
+ modifications, and in Source or Object form, provided that You
57
+ meet the following conditions:
58
+
59
+ (a) You must give any other recipients of the Work or Derivative
60
+ Works a copy of this License; and
61
+
62
+ (b) You must cause any modified files to carry prominent notices
63
+ stating that You changed the files; and
64
+
65
+ (c) You must retain, in the Source form of any Derivative Works
66
+ that You distribute, all copyright, patent, trademark, and
67
+ attribution notices from the Source form of the Work; and
68
+
69
+ (d) If the Work includes a "NOTICE" text file, you must include
70
+ a readable copy of the attribution notices contained within
71
+ such NOTICE file.
72
+
73
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
74
+ any Contribution submitted for inclusion in the Work by You shall
75
+ be under the terms and conditions of this License.
76
+
77
+ 6. Trademarks. This License does not grant permission to use the trade
78
+ names, trademarks, service marks, or product names of the Licensor.
79
+
80
+ 7. Disclaimer of Warranty. Unless required by applicable law or
81
+ agreed to in writing, the Licensor provides the Work on an "AS IS"
82
+ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
83
+
84
+ 8. Limitation of Liability. In no event shall any Contributor be
85
+ liable for any damages arising from this License or out of the use
86
+ or inability to use the Work.
87
+
88
+ 9. Accepting Warranty or Additional Liability. While redistributing
89
+ the Work, You may offer acceptance of support, warranty, indemnity,
90
+ or other liability obligations consistent with this License.