project-documentation 0.2.0__tar.gz
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-0.2.0/.gitignore +41 -0
- project_documentation-0.2.0/CHANGELOG.md +34 -0
- project_documentation-0.2.0/LICENSE +90 -0
- project_documentation-0.2.0/PKG-INFO +139 -0
- project_documentation-0.2.0/README.md +105 -0
- project_documentation-0.2.0/action.yml +232 -0
- project_documentation-0.2.0/docs/usage.md +135 -0
- project_documentation-0.2.0/examples/e-foc/documentation/theory.md +31 -0
- project_documentation-0.2.0/examples/e-foc/requirement.schema.json +23 -0
- project_documentation-0.2.0/examples/e-foc/requirements/foc.yaml +18 -0
- project_documentation-0.2.0/pyproject.toml +123 -0
- project_documentation-0.2.0/src/project_documentation/__init__.py +3 -0
- project_documentation-0.2.0/src/project_documentation/build_documentation_pdfs.py +119 -0
- project_documentation-0.2.0/src/project_documentation/generate_requirements_pdf.py +62 -0
- project_documentation-0.2.0/src/project_documentation/generate_traceability_matrix.py +278 -0
- project_documentation-0.2.0/src/project_documentation/validate_documents.py +252 -0
- project_documentation-0.2.0/src/project_documentation/validate_requirements.py +42 -0
- project_documentation-0.2.0/tests/__init__.py +1 -0
- project_documentation-0.2.0/tests/unit/__init__.py +1 -0
- project_documentation-0.2.0/tests/unit/test_generate_traceability_matrix.py +129 -0
- project_documentation-0.2.0/tests/unit/test_validate_documents.py +239 -0
- project_documentation-0.2.0/tests/unit/test_validate_requirements.py +175 -0
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# Distribution / packaging
|
|
7
|
+
build/
|
|
8
|
+
dist/
|
|
9
|
+
*.egg-info/
|
|
10
|
+
*.egg
|
|
11
|
+
|
|
12
|
+
# Test / coverage
|
|
13
|
+
.pytest_cache/
|
|
14
|
+
.coverage
|
|
15
|
+
.coverage.*
|
|
16
|
+
htmlcov/
|
|
17
|
+
coverage.xml
|
|
18
|
+
.tox/
|
|
19
|
+
.nox/
|
|
20
|
+
|
|
21
|
+
# Type-check / lint caches
|
|
22
|
+
.mypy_cache/
|
|
23
|
+
.ruff_cache/
|
|
24
|
+
.dmypy.json
|
|
25
|
+
|
|
26
|
+
# IDE
|
|
27
|
+
.vscode/
|
|
28
|
+
.idea/
|
|
29
|
+
*.swp
|
|
30
|
+
|
|
31
|
+
# Virtualenv
|
|
32
|
+
.venv/
|
|
33
|
+
venv/
|
|
34
|
+
env/
|
|
35
|
+
|
|
36
|
+
# Generated documentation artefacts
|
|
37
|
+
docs-pdf/
|
|
38
|
+
documentation/output/
|
|
39
|
+
|
|
40
|
+
# Tooling output
|
|
41
|
+
*.log
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.2.0](https://github.com/embedded-pro/project-documentation/compare/v0.1.0...v0.2.0) (2026-05-24)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Features
|
|
12
|
+
|
|
13
|
+
* initial project-documentation v0.1.0 ([cc9e17f](https://github.com/embedded-pro/project-documentation/commit/cc9e17fe8bfccbaaf58b27a226e68a851e251769))
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
### Bug Fixes
|
|
17
|
+
|
|
18
|
+
* add missing type annotations to satisfy mypy strict ([358f36a](https://github.com/embedded-pro/project-documentation/commit/358f36ad6cd173ff458b2d2bf4353159afef3897))
|
|
19
|
+
* sort imports to satisfy ruff I001 ([5b01b77](https://github.com/embedded-pro/project-documentation/commit/5b01b77031a28aa93342da2c60cb299ed0d14ffa))
|
|
20
|
+
|
|
21
|
+
## [0.1.0] - 2026-05-24
|
|
22
|
+
|
|
23
|
+
### Added
|
|
24
|
+
|
|
25
|
+
- Initial release with five documentation pipeline capabilities:
|
|
26
|
+
- `validate-requirements`: validates YAML requirement files against a JSON schema
|
|
27
|
+
- `validate-documents`: validates Markdown documentation frontmatter and required sections
|
|
28
|
+
- `generate-requirements-pdf`: generates a PDF from YAML requirement files using a Markdown template
|
|
29
|
+
- `build-pdfs`: converts Markdown documentation directories and YAML requirements to PDFs
|
|
30
|
+
- `traceability-matrix`: generates a requirements-vs-SIL traceability matrix in Markdown and optionally PDF
|
|
31
|
+
- GitHub composite action (`action.yml`) with feature-flag inputs for each capability
|
|
32
|
+
- Full test suite (unit tests for all modules)
|
|
33
|
+
- CI workflow: lint, type-check, unit tests, coverage, action smoke test
|
|
34
|
+
- Release automation via release-please
|
|
@@ -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.
|
|
@@ -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,105 @@
|
|
|
1
|
+
# project-documentation
|
|
2
|
+
|
|
3
|
+
[](https://github.com/embedded-pro/project-documentation/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/project-documentation/)
|
|
5
|
+
[](https://pypi.org/project/project-documentation/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
> Documentation pipeline for embedded projects — CI-friendly, framework-agnostic.
|
|
9
|
+
|
|
10
|
+
`project-documentation` is a GitHub composite action and Python package that covers the full documentation lifecycle for embedded software projects:
|
|
11
|
+
|
|
12
|
+
- **Validate requirements** — check YAML requirement files against a JSON schema
|
|
13
|
+
- **Validate documents** — enforce frontmatter fields and required sections in Markdown architecture/design/theory documents
|
|
14
|
+
- **Generate requirements PDF** — render YAML requirements to a versioned PDF via a Markdown template
|
|
15
|
+
- **Build documentation PDFs** — convert Markdown documentation directories and YAML requirements to PDFs using Pandoc
|
|
16
|
+
- **Traceability matrix** — map requirements to Gherkin scenarios (with optional JUnit pass/fail status), output Markdown and optionally PDF
|
|
17
|
+
|
|
18
|
+
## ✨ Features
|
|
19
|
+
|
|
20
|
+
| Capability | Description |
|
|
21
|
+
|---|---|
|
|
22
|
+
| Requirements validation | JSON schema validation for YAML requirement files |
|
|
23
|
+
| Document validation | Frontmatter fields, required H2 sections, no code blocks in design docs |
|
|
24
|
+
| Requirements PDF | Template-driven PDF from YAML requirements |
|
|
25
|
+
| Documentation PDFs | Per-directory Markdown → PDF + combined requirements PDF |
|
|
26
|
+
| Traceability matrix | Requirements ↔ scenarios mapping with coverage statistics |
|
|
27
|
+
| PR comment | Idempotent PR comments (traceability matrix) |
|
|
28
|
+
| GitHub Action | Composite action with feature flags for each capability |
|
|
29
|
+
|
|
30
|
+
## 🚀 Quickstart
|
|
31
|
+
|
|
32
|
+
### 1. Install
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
pip install project-documentation
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### 2. Use in GitHub Actions
|
|
39
|
+
|
|
40
|
+
```yaml
|
|
41
|
+
- uses: embedded-pro/project-documentation@v0
|
|
42
|
+
with:
|
|
43
|
+
run-validate-requirements: 'true'
|
|
44
|
+
run-validate-documents: 'true'
|
|
45
|
+
run-generate-requirements-pdf: 'true'
|
|
46
|
+
run-build-documentation-pdfs: 'true'
|
|
47
|
+
run-traceability-matrix: 'true'
|
|
48
|
+
version: ${{ github.ref_name }}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
See [docs/usage.md](docs/usage.md) for the full input/output reference.
|
|
52
|
+
|
|
53
|
+
### 3. Run from the command line
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# Validate requirements against a JSON schema
|
|
57
|
+
project-documentation-validate-requirements \
|
|
58
|
+
--schema documentation/tools/requirement.schema.json \
|
|
59
|
+
--requirements-dir documentation/requirements
|
|
60
|
+
|
|
61
|
+
# Validate Markdown documentation
|
|
62
|
+
project-documentation-validate-documents \
|
|
63
|
+
--documents-dir documentation \
|
|
64
|
+
--doc-type architecture
|
|
65
|
+
|
|
66
|
+
# Generate requirements PDF
|
|
67
|
+
project-documentation-generate-requirements-pdf \
|
|
68
|
+
--requirements-dir documentation/requirements \
|
|
69
|
+
--template documentation/templates/requirements.md \
|
|
70
|
+
--output documentation/output/requirements.pdf
|
|
71
|
+
|
|
72
|
+
# Build all documentation PDFs
|
|
73
|
+
project-documentation-build-pdfs \
|
|
74
|
+
--version v1.2.3 \
|
|
75
|
+
--output-dir docs-pdf \
|
|
76
|
+
--docs-dirs documentation/architecture documentation/design documentation/theory \
|
|
77
|
+
--requirements-dir documentation/requirements
|
|
78
|
+
|
|
79
|
+
# Generate traceability matrix
|
|
80
|
+
project-documentation-traceability-matrix \
|
|
81
|
+
--requirements-dir documentation/requirements \
|
|
82
|
+
--features-dir integration_tests/software_in_the_loop/features \
|
|
83
|
+
--output docs-pdf/traceability-matrix.md \
|
|
84
|
+
--junit-xml sil-test-report.xml
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## 📚 Documentation
|
|
88
|
+
|
|
89
|
+
| File | Contents |
|
|
90
|
+
|---|---|
|
|
91
|
+
| [docs/usage.md](docs/usage.md) | CLI flags, action inputs/outputs, examples |
|
|
92
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, testing, release process |
|
|
93
|
+
| [CHANGELOG.md](CHANGELOG.md) | Version history |
|
|
94
|
+
|
|
95
|
+
## ⚠️ System dependencies
|
|
96
|
+
|
|
97
|
+
The PDF-generating capabilities require:
|
|
98
|
+
- `pandoc` — document converter
|
|
99
|
+
- `pdflatex` (via `texlive-latex-recommended`, `texlive-latex-extra`, `texlive-fonts-recommended`)
|
|
100
|
+
|
|
101
|
+
The GitHub Action installs these automatically when any PDF feature flag is enabled.
|
|
102
|
+
|
|
103
|
+
## 📄 License
|
|
104
|
+
|
|
105
|
+
Apache-2.0 — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
name: 'Project Documentation'
|
|
2
|
+
description: >-
|
|
3
|
+
Documentation pipeline for embedded projects: validates YAML requirements
|
|
4
|
+
and Markdown documents, generates requirements PDFs, builds documentation
|
|
5
|
+
PDFs, and creates a requirements traceability matrix.
|
|
6
|
+
author: 'project-documentation contributors'
|
|
7
|
+
|
|
8
|
+
branding:
|
|
9
|
+
icon: 'book-open'
|
|
10
|
+
color: 'green'
|
|
11
|
+
|
|
12
|
+
inputs:
|
|
13
|
+
# ── Feature flags ────────────────────────────────────────────────────────────
|
|
14
|
+
run-validate-requirements:
|
|
15
|
+
description: "Validate YAML requirement files against their JSON schema"
|
|
16
|
+
required: false
|
|
17
|
+
default: 'false'
|
|
18
|
+
run-validate-documents:
|
|
19
|
+
description: "Validate Markdown documentation files against templates"
|
|
20
|
+
required: false
|
|
21
|
+
default: 'false'
|
|
22
|
+
run-generate-requirements-pdf:
|
|
23
|
+
description: "Generate a PDF from YAML requirement files using a template"
|
|
24
|
+
required: false
|
|
25
|
+
default: 'false'
|
|
26
|
+
run-build-documentation-pdfs:
|
|
27
|
+
description: "Convert Markdown documentation and YAML requirements to PDFs"
|
|
28
|
+
required: false
|
|
29
|
+
default: 'false'
|
|
30
|
+
run-traceability-matrix:
|
|
31
|
+
description: "Generate the requirements-vs-SIL traceability matrix"
|
|
32
|
+
required: false
|
|
33
|
+
default: 'false'
|
|
34
|
+
|
|
35
|
+
# ── Shared ───────────────────────────────────────────────────────────────────
|
|
36
|
+
requirements-dir:
|
|
37
|
+
description: "Directory containing YAML requirement files"
|
|
38
|
+
required: false
|
|
39
|
+
default: "documentation/requirements"
|
|
40
|
+
|
|
41
|
+
# ── validate-requirements ────────────────────────────────────────────────────
|
|
42
|
+
schema-path:
|
|
43
|
+
description: "Path to the JSON schema file for requirements validation"
|
|
44
|
+
required: false
|
|
45
|
+
default: "documentation/tools/requirement.schema.json"
|
|
46
|
+
|
|
47
|
+
# ── validate-documents ───────────────────────────────────────────────────────
|
|
48
|
+
documents-dir:
|
|
49
|
+
description: "Directory to search for documentation files"
|
|
50
|
+
required: false
|
|
51
|
+
default: "documentation"
|
|
52
|
+
doc-type:
|
|
53
|
+
description: "Filter by document type: architecture, design, theory, or all"
|
|
54
|
+
required: false
|
|
55
|
+
default: "all"
|
|
56
|
+
|
|
57
|
+
# ── generate-requirements-pdf ────────────────────────────────────────────────
|
|
58
|
+
template-path:
|
|
59
|
+
description: "Path to the Markdown template for requirements PDF"
|
|
60
|
+
required: false
|
|
61
|
+
default: "documentation/templates/requirements.md"
|
|
62
|
+
requirements-pdf-output:
|
|
63
|
+
description: "Output path for the generated requirements PDF"
|
|
64
|
+
required: false
|
|
65
|
+
default: "documentation/output/requirements.pdf"
|
|
66
|
+
upload-requirements-pdf:
|
|
67
|
+
description: "Upload the generated requirements PDF as a workflow artifact"
|
|
68
|
+
required: false
|
|
69
|
+
default: 'false'
|
|
70
|
+
|
|
71
|
+
# ── build-documentation-pdfs ─────────────────────────────────────────────────
|
|
72
|
+
version:
|
|
73
|
+
description: "Release version tag used to name output files (e.g. v1.2.3)"
|
|
74
|
+
required: false
|
|
75
|
+
default: ""
|
|
76
|
+
output-dir:
|
|
77
|
+
description: "Output directory for generated documentation PDFs"
|
|
78
|
+
required: false
|
|
79
|
+
default: "docs-pdf"
|
|
80
|
+
docs-dirs:
|
|
81
|
+
description: >-
|
|
82
|
+
Space-separated list of documentation directories to convert to PDF
|
|
83
|
+
required: false
|
|
84
|
+
default: "documentation/architecture documentation/design documentation/theory"
|
|
85
|
+
artifact-name:
|
|
86
|
+
description: "Name for the uploaded documentation PDFs artifact"
|
|
87
|
+
required: false
|
|
88
|
+
default: "documentation-pdfs"
|
|
89
|
+
|
|
90
|
+
# ── traceability-matrix ──────────────────────────────────────────────────────
|
|
91
|
+
features-dir:
|
|
92
|
+
description: "Directory containing Gherkin feature files"
|
|
93
|
+
required: false
|
|
94
|
+
default: "integration_tests/software_in_the_loop/features"
|
|
95
|
+
junit-xml:
|
|
96
|
+
description: "Path to JUnit XML from SIL test run (optional; adds status column)"
|
|
97
|
+
required: false
|
|
98
|
+
default: ""
|
|
99
|
+
matrix-output:
|
|
100
|
+
description: "Output path for the generated traceability matrix Markdown file"
|
|
101
|
+
required: false
|
|
102
|
+
default: "docs-pdf/traceability-matrix.md"
|
|
103
|
+
matrix-pdf-output:
|
|
104
|
+
description: "If set, also convert the traceability matrix to a PDF at this path"
|
|
105
|
+
required: false
|
|
106
|
+
default: ""
|
|
107
|
+
|
|
108
|
+
# ── Tooling ──────────────────────────────────────────────────────────────────
|
|
109
|
+
python-version:
|
|
110
|
+
description: "Python version to set up"
|
|
111
|
+
required: false
|
|
112
|
+
default: "3.11"
|
|
113
|
+
package-version:
|
|
114
|
+
description: >-
|
|
115
|
+
pip-installable version specifier for project-documentation (e.g.
|
|
116
|
+
"==0.1.0" or "@git+https://…"). Empty installs the latest from PyPI.
|
|
117
|
+
required: false
|
|
118
|
+
default: ""
|
|
119
|
+
|
|
120
|
+
outputs:
|
|
121
|
+
output-dir:
|
|
122
|
+
description: "Path to the directory containing generated documentation PDFs"
|
|
123
|
+
value: ${{ inputs.output-dir }}
|
|
124
|
+
matrix-path:
|
|
125
|
+
description: "Path to the generated Markdown traceability matrix"
|
|
126
|
+
value: ${{ inputs.matrix-output }}
|
|
127
|
+
|
|
128
|
+
runs:
|
|
129
|
+
using: "composite"
|
|
130
|
+
steps:
|
|
131
|
+
- name: Set up Python
|
|
132
|
+
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
|
|
133
|
+
with:
|
|
134
|
+
python-version: ${{ inputs.python-version }}
|
|
135
|
+
|
|
136
|
+
- name: Install project-documentation
|
|
137
|
+
shell: bash
|
|
138
|
+
run: |
|
|
139
|
+
set -euo pipefail
|
|
140
|
+
if [[ -n "${{ inputs.package-version }}" ]]; then
|
|
141
|
+
python -m pip install --quiet "project-documentation${{ inputs.package-version }}"
|
|
142
|
+
else
|
|
143
|
+
python -m pip install --quiet project-documentation
|
|
144
|
+
fi
|
|
145
|
+
|
|
146
|
+
- name: Install Pandoc and LaTeX
|
|
147
|
+
if: >-
|
|
148
|
+
inputs.run-generate-requirements-pdf == 'true' ||
|
|
149
|
+
inputs.run-build-documentation-pdfs == 'true' ||
|
|
150
|
+
(inputs.run-traceability-matrix == 'true' && inputs.matrix-pdf-output != '')
|
|
151
|
+
shell: bash
|
|
152
|
+
run: |
|
|
153
|
+
sudo apt-get update -qq
|
|
154
|
+
sudo apt-get install -y --no-install-recommends \
|
|
155
|
+
pandoc \
|
|
156
|
+
texlive-latex-recommended \
|
|
157
|
+
texlive-latex-extra \
|
|
158
|
+
texlive-fonts-recommended
|
|
159
|
+
|
|
160
|
+
- name: Validate requirements
|
|
161
|
+
if: inputs.run-validate-requirements == 'true'
|
|
162
|
+
shell: bash
|
|
163
|
+
run: |
|
|
164
|
+
project-documentation-validate-requirements \
|
|
165
|
+
--schema "${{ inputs.schema-path }}" \
|
|
166
|
+
--requirements-dir "${{ inputs.requirements-dir }}"
|
|
167
|
+
|
|
168
|
+
- name: Validate documents
|
|
169
|
+
if: inputs.run-validate-documents == 'true'
|
|
170
|
+
shell: bash
|
|
171
|
+
run: |
|
|
172
|
+
project-documentation-validate-documents \
|
|
173
|
+
--documents-dir "${{ inputs.documents-dir }}" \
|
|
174
|
+
--doc-type "${{ inputs.doc-type }}"
|
|
175
|
+
|
|
176
|
+
- name: Generate requirements PDF
|
|
177
|
+
if: inputs.run-generate-requirements-pdf == 'true'
|
|
178
|
+
shell: bash
|
|
179
|
+
run: |
|
|
180
|
+
project-documentation-generate-requirements-pdf \
|
|
181
|
+
--requirements-dir "${{ inputs.requirements-dir }}" \
|
|
182
|
+
--template "${{ inputs.template-path }}" \
|
|
183
|
+
--output "${{ inputs.requirements-pdf-output }}"
|
|
184
|
+
|
|
185
|
+
- name: Upload requirements PDF
|
|
186
|
+
if: inputs.run-generate-requirements-pdf == 'true' && inputs.upload-requirements-pdf == 'true'
|
|
187
|
+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
|
|
188
|
+
with:
|
|
189
|
+
name: requirements-pdf
|
|
190
|
+
path: ${{ inputs.requirements-pdf-output }}
|
|
191
|
+
if-no-files-found: warn
|
|
192
|
+
|
|
193
|
+
- name: Build documentation PDFs
|
|
194
|
+
if: inputs.run-build-documentation-pdfs == 'true'
|
|
195
|
+
shell: bash
|
|
196
|
+
run: |
|
|
197
|
+
project-documentation-build-pdfs \
|
|
198
|
+
--version "${{ inputs.version }}" \
|
|
199
|
+
--output-dir "${{ inputs.output-dir }}" \
|
|
200
|
+
--docs-dirs ${{ inputs.docs-dirs }} \
|
|
201
|
+
--requirements-dir "${{ inputs.requirements-dir }}"
|
|
202
|
+
|
|
203
|
+
- name: Upload documentation PDFs
|
|
204
|
+
if: inputs.run-build-documentation-pdfs == 'true'
|
|
205
|
+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
|
|
206
|
+
with:
|
|
207
|
+
name: ${{ inputs.artifact-name }}
|
|
208
|
+
path: ${{ inputs.output-dir }}/*.pdf
|
|
209
|
+
if-no-files-found: warn
|
|
210
|
+
|
|
211
|
+
- name: Generate traceability matrix
|
|
212
|
+
if: inputs.run-traceability-matrix == 'true'
|
|
213
|
+
shell: bash
|
|
214
|
+
run: |
|
|
215
|
+
project-documentation-traceability-matrix \
|
|
216
|
+
--requirements-dir "${{ inputs.requirements-dir }}" \
|
|
217
|
+
--features-dir "${{ inputs.features-dir }}" \
|
|
218
|
+
${{ inputs.junit-xml != '' && format('--junit-xml "{0}"', inputs.junit-xml) || '' }} \
|
|
219
|
+
--output "${{ inputs.matrix-output }}"
|
|
220
|
+
|
|
221
|
+
- name: Convert traceability matrix to PDF
|
|
222
|
+
if: inputs.run-traceability-matrix == 'true' && inputs.matrix-pdf-output != ''
|
|
223
|
+
shell: bash
|
|
224
|
+
run: |
|
|
225
|
+
pandoc \
|
|
226
|
+
--pdf-engine=pdflatex \
|
|
227
|
+
-V geometry:margin=2cm \
|
|
228
|
+
-V fontsize=11pt \
|
|
229
|
+
--toc \
|
|
230
|
+
--standalone \
|
|
231
|
+
-o "${{ inputs.matrix-pdf-output }}" \
|
|
232
|
+
"${{ inputs.matrix-output }}"
|