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.
- project_documentation/__init__.py +3 -0
- project_documentation/build_documentation_pdfs.py +119 -0
- project_documentation/generate_requirements_pdf.py +62 -0
- project_documentation/generate_traceability_matrix.py +278 -0
- project_documentation/validate_documents.py +252 -0
- project_documentation/validate_requirements.py +42 -0
- project_documentation-0.2.0.dist-info/METADATA +139 -0
- project_documentation-0.2.0.dist-info/RECORD +11 -0
- project_documentation-0.2.0.dist-info/WHEEL +4 -0
- project_documentation-0.2.0.dist-info/entry_points.txt +6 -0
- project_documentation-0.2.0.dist-info/licenses/LICENSE +90 -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 () 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
|
+
[](https://github.com/embedded-pro/project-documentation/actions/workflows/ci.yml)
|
|
38
|
+
[](https://pypi.org/project/project-documentation/)
|
|
39
|
+
[](https://pypi.org/project/project-documentation/)
|
|
40
|
+
[](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,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.
|