project-documentation 0.2.0__tar.gz → 0.4.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.4.0/CHANGELOG.md +65 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/PKG-INFO +5 -3
- {project_documentation-0.2.0 → project_documentation-0.4.0}/README.md +3 -1
- {project_documentation-0.2.0 → project_documentation-0.4.0}/action.yml +38 -7
- {project_documentation-0.2.0 → project_documentation-0.4.0}/docs/usage.md +3 -2
- project_documentation-0.4.0/examples/e-foc/documentation/architecture.md +30 -0
- project_documentation-0.4.0/examples/e-foc/documentation/design.md +23 -0
- project_documentation-0.4.0/examples/e-foc/features/foc.feature +24 -0
- project_documentation-0.4.0/examples/e-foc/templates/requirements.md +6 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/pyproject.toml +1 -1
- {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/__init__.py +1 -1
- {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/build_documentation_pdfs.py +16 -6
- {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/generate_requirements_pdf.py +28 -26
- project_documentation-0.4.0/tests/integration/__init__.py +1 -0
- project_documentation-0.4.0/tests/integration/test_cli_integration.py +357 -0
- project_documentation-0.4.0/tests/unit/test_build_documentation_pdfs.py +163 -0
- project_documentation-0.4.0/tests/unit/test_generate_requirements_pdf.py +132 -0
- project_documentation-0.2.0/CHANGELOG.md +0 -34
- {project_documentation-0.2.0 → project_documentation-0.4.0}/.gitignore +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/LICENSE +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/examples/e-foc/documentation/theory.md +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/examples/e-foc/requirement.schema.json +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/examples/e-foc/requirements/foc.yaml +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/generate_traceability_matrix.py +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/validate_documents.py +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/validate_requirements.py +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/tests/__init__.py +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/tests/unit/__init__.py +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/tests/unit/test_generate_traceability_matrix.py +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/tests/unit/test_validate_documents.py +0 -0
- {project_documentation-0.2.0 → project_documentation-0.4.0}/tests/unit/test_validate_requirements.py +0 -0
|
@@ -0,0 +1,65 @@
|
|
|
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.4.0](https://github.com/embedded-pro/project-documentation/compare/v0.3.0...v0.4.0) (2026-11-21)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Features
|
|
12
|
+
|
|
13
|
+
* Name the PDFs after the project; the action runs its own source ([b687ff4](https://github.com/embedded-pro/project-documentation/commit/b687ff41f49b4eba92dc688f1ef0b7971f21828d))
|
|
14
|
+
* Name the PDFs after the project; the action runs its own source ([748f0f3](https://github.com/embedded-pro/project-documentation/commit/748f0f325d90233f5965b2e9c03d50f31f8db6a2))
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
### Bug Fixes
|
|
18
|
+
|
|
19
|
+
* **release:** Publish with gh-action-pypi-publish v1.14.3 ([a54d0a2](https://github.com/embedded-pro/project-documentation/commit/a54d0a2fbd827fa9ad314521e7272ab8f7c7bf64))
|
|
20
|
+
|
|
21
|
+
## [0.3.0](https://github.com/embedded-pro/project-documentation/compare/v0.2.0...v0.3.0) (2026-11-07)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### Features
|
|
25
|
+
|
|
26
|
+
* integration tests, unit tests for all modules, codeql, fix pdf prefix and engine ([62c3fcc](https://github.com/embedded-pro/project-documentation/commit/62c3fcc4bc9f575a562b7377358e0093e2232596))
|
|
27
|
+
* run the action inside the embedded-devcontainer-documentation container ([62d3d36](https://github.com/embedded-pro/project-documentation/commit/62d3d36f72dba1a107af94f71103442afee09e3c))
|
|
28
|
+
* run the action inside the embedded-devcontainer-documentation container ([6f11819](https://github.com/embedded-pro/project-documentation/commit/6f118192bb8b509c3c5c2e1c8ce7fce351cf03af))
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
### Bug Fixes
|
|
32
|
+
|
|
33
|
+
* add lmodern to LaTeX install for lmodern.sty ([54fca1c](https://github.com/embedded-pro/project-documentation/commit/54fca1cb9925af16e53bd9d2640d1285560d295b))
|
|
34
|
+
* add lmodern to LaTeX install for lmodern.sty ([df9b912](https://github.com/embedded-pro/project-documentation/commit/df9b9120a2be16def01b465964a8543bcbe76728))
|
|
35
|
+
* rewrite yoda condition in test (SIM300) ([714e373](https://github.com/embedded-pro/project-documentation/commit/714e373c832189bdc19534fe827fb605fb87421f))
|
|
36
|
+
* upgrade pip in the action virtual environment ([6fc0a8d](https://github.com/embedded-pro/project-documentation/commit/6fc0a8def30c83c2e0008bbcf1a072b8244188fb))
|
|
37
|
+
* use REQ-FOC-001 format in traceability test (matches REQ-[A-Z]+-\d+ regex) ([5dd98cc](https://github.com/embedded-pro/project-documentation/commit/5dd98ccc3e04a9ced57aa8102ae3b1f64b8332c5))
|
|
38
|
+
|
|
39
|
+
## [0.2.0](https://github.com/embedded-pro/project-documentation/compare/v0.1.0...v0.2.0) (2026-05-24)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
### Features
|
|
43
|
+
|
|
44
|
+
* initial project-documentation v0.1.0 ([cc9e17f](https://github.com/embedded-pro/project-documentation/commit/cc9e17fe8bfccbaaf58b27a226e68a851e251769))
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
### Bug Fixes
|
|
48
|
+
|
|
49
|
+
* add missing type annotations to satisfy mypy strict ([358f36a](https://github.com/embedded-pro/project-documentation/commit/358f36ad6cd173ff458b2d2bf4353159afef3897))
|
|
50
|
+
* sort imports to satisfy ruff I001 ([5b01b77](https://github.com/embedded-pro/project-documentation/commit/5b01b77031a28aa93342da2c60cb299ed0d14ffa))
|
|
51
|
+
|
|
52
|
+
## [0.1.0] - 2026-05-24
|
|
53
|
+
|
|
54
|
+
### Added
|
|
55
|
+
|
|
56
|
+
- Initial release with five documentation pipeline capabilities:
|
|
57
|
+
- `validate-requirements`: validates YAML requirement files against a JSON schema
|
|
58
|
+
- `validate-documents`: validates Markdown documentation frontmatter and required sections
|
|
59
|
+
- `generate-requirements-pdf`: generates a PDF from YAML requirement files using a Markdown template
|
|
60
|
+
- `build-pdfs`: converts Markdown documentation directories and YAML requirements to PDFs
|
|
61
|
+
- `traceability-matrix`: generates a requirements-vs-SIL traceability matrix in Markdown and optionally PDF
|
|
62
|
+
- GitHub composite action (`action.yml`) with feature-flag inputs for each capability
|
|
63
|
+
- Full test suite (unit tests for all modules)
|
|
64
|
+
- CI workflow: lint, type-check, unit tests, coverage, action smoke test
|
|
65
|
+
- Release automation via release-please
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: project-documentation
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.0
|
|
4
4
|
Summary: Documentation pipeline for embedded projects: validates requirements and design documents, generates PDFs, and produces a traceability matrix.
|
|
5
5
|
Project-URL: Homepage, https://github.com/embedded-pro/project-documentation
|
|
6
6
|
Project-URL: Documentation, https://github.com/embedded-pro/project-documentation/tree/main/docs
|
|
@@ -106,6 +106,7 @@ project-documentation-generate-requirements-pdf \
|
|
|
106
106
|
# Build all documentation PDFs
|
|
107
107
|
project-documentation-build-pdfs \
|
|
108
108
|
--version v1.2.3 \
|
|
109
|
+
--name-prefix my_project \
|
|
109
110
|
--output-dir docs-pdf \
|
|
110
111
|
--docs-dirs documentation/architecture documentation/design documentation/theory \
|
|
111
112
|
--requirements-dir documentation/requirements
|
|
@@ -132,7 +133,8 @@ The PDF-generating capabilities require:
|
|
|
132
133
|
- `pandoc` — document converter
|
|
133
134
|
- `pdflatex` (via `texlive-latex-recommended`, `texlive-latex-extra`, `texlive-fonts-recommended`)
|
|
134
135
|
|
|
135
|
-
The GitHub Action installs these automatically when any PDF feature flag is enabled.
|
|
136
|
+
The GitHub Action installs these automatically when any PDF feature flag is enabled, unless they are already available.
|
|
137
|
+
To skip the installation entirely, run the job in the [`embedded-devcontainer-documentation`](https://hub.docker.com/r/gabrielfrasantos/embedded-devcontainer-documentation) container image and set `python-version: ""`.
|
|
136
138
|
|
|
137
139
|
## 📄 License
|
|
138
140
|
|
|
@@ -72,6 +72,7 @@ project-documentation-generate-requirements-pdf \
|
|
|
72
72
|
# Build all documentation PDFs
|
|
73
73
|
project-documentation-build-pdfs \
|
|
74
74
|
--version v1.2.3 \
|
|
75
|
+
--name-prefix my_project \
|
|
75
76
|
--output-dir docs-pdf \
|
|
76
77
|
--docs-dirs documentation/architecture documentation/design documentation/theory \
|
|
77
78
|
--requirements-dir documentation/requirements
|
|
@@ -98,7 +99,8 @@ The PDF-generating capabilities require:
|
|
|
98
99
|
- `pandoc` — document converter
|
|
99
100
|
- `pdflatex` (via `texlive-latex-recommended`, `texlive-latex-extra`, `texlive-fonts-recommended`)
|
|
100
101
|
|
|
101
|
-
The GitHub Action installs these automatically when any PDF feature flag is enabled.
|
|
102
|
+
The GitHub Action installs these automatically when any PDF feature flag is enabled, unless they are already available.
|
|
103
|
+
To skip the installation entirely, run the job in the [`embedded-devcontainer-documentation`](https://hub.docker.com/r/gabrielfrasantos/embedded-devcontainer-documentation) container image and set `python-version: ""`.
|
|
102
104
|
|
|
103
105
|
## 📄 License
|
|
104
106
|
|
|
@@ -73,6 +73,12 @@ inputs:
|
|
|
73
73
|
description: "Release version tag used to name output files (e.g. v1.2.3)"
|
|
74
74
|
required: false
|
|
75
75
|
default: ""
|
|
76
|
+
name-prefix:
|
|
77
|
+
description: >-
|
|
78
|
+
Prefix for every documentation PDF file name, usually the project name
|
|
79
|
+
(e.g. my_project gives my_project-design-safety-v1.2.3.pdf). Empty adds none.
|
|
80
|
+
required: false
|
|
81
|
+
default: ""
|
|
76
82
|
output-dir:
|
|
77
83
|
description: "Output directory for generated documentation PDFs"
|
|
78
84
|
required: false
|
|
@@ -107,13 +113,16 @@ inputs:
|
|
|
107
113
|
|
|
108
114
|
# ── Tooling ──────────────────────────────────────────────────────────────────
|
|
109
115
|
python-version:
|
|
110
|
-
description:
|
|
116
|
+
description: >-
|
|
117
|
+
Python version to set up. Set to an empty string to use the python3 that is
|
|
118
|
+
already on the PATH, e.g. when running inside a container image.
|
|
111
119
|
required: false
|
|
112
120
|
default: "3.11"
|
|
113
121
|
package-version:
|
|
114
122
|
description: >-
|
|
115
123
|
pip-installable version specifier for project-documentation (e.g.
|
|
116
|
-
"==0.1.0" or "@git+https://…"). Empty installs the
|
|
124
|
+
"==0.1.0" or "@git+https://…"). Empty installs the package from this
|
|
125
|
+
action's own source, so the code that runs is the ref the workflow pins.
|
|
117
126
|
required: false
|
|
118
127
|
default: ""
|
|
119
128
|
|
|
@@ -129,19 +138,27 @@ runs:
|
|
|
129
138
|
using: "composite"
|
|
130
139
|
steps:
|
|
131
140
|
- name: Set up Python
|
|
141
|
+
if: inputs.python-version != ''
|
|
132
142
|
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
|
|
133
143
|
with:
|
|
134
144
|
python-version: ${{ inputs.python-version }}
|
|
135
145
|
|
|
146
|
+
# Install into a virtual environment so this also works with an externally
|
|
147
|
+
# managed system Python (PEP 668), e.g. inside a container image.
|
|
136
148
|
- name: Install project-documentation
|
|
137
149
|
shell: bash
|
|
138
150
|
run: |
|
|
139
151
|
set -euo pipefail
|
|
152
|
+
venv="${RUNNER_TEMP}/project-documentation-venv"
|
|
153
|
+
python3 -m venv "${venv}"
|
|
154
|
+
# The pip bundled with the venv can be too old to parse "name @ url" requirements.
|
|
155
|
+
"${venv}/bin/python" -m pip install --quiet --upgrade pip
|
|
140
156
|
if [[ -n "${{ inputs.package-version }}" ]]; then
|
|
141
|
-
python -m pip install --quiet "project-documentation${{ inputs.package-version }}"
|
|
157
|
+
"${venv}/bin/python" -m pip install --quiet "project-documentation${{ inputs.package-version }}"
|
|
142
158
|
else
|
|
143
|
-
python -m pip install --quiet
|
|
159
|
+
"${venv}/bin/python" -m pip install --quiet "${GITHUB_ACTION_PATH}"
|
|
144
160
|
fi
|
|
161
|
+
echo "${venv}/bin" >> "${GITHUB_PATH}"
|
|
145
162
|
|
|
146
163
|
- name: Install Pandoc and LaTeX
|
|
147
164
|
if: >-
|
|
@@ -150,12 +167,25 @@ runs:
|
|
|
150
167
|
(inputs.run-traceability-matrix == 'true' && inputs.matrix-pdf-output != '')
|
|
151
168
|
shell: bash
|
|
152
169
|
run: |
|
|
153
|
-
|
|
154
|
-
|
|
170
|
+
set -euo pipefail
|
|
171
|
+
# Skip the installation when the tools are already available, e.g. in the
|
|
172
|
+
# embedded-devcontainer-documentation container image.
|
|
173
|
+
if command -v pandoc >/dev/null 2>&1 && command -v pdflatex >/dev/null 2>&1 \
|
|
174
|
+
&& kpsewhich lmodern.sty titlesec.sty >/dev/null 2>&1; then
|
|
175
|
+
echo "Pandoc and LaTeX are already installed"
|
|
176
|
+
exit 0
|
|
177
|
+
fi
|
|
178
|
+
sudo=""
|
|
179
|
+
if [[ "$(id -u)" -ne 0 ]]; then
|
|
180
|
+
sudo="sudo"
|
|
181
|
+
fi
|
|
182
|
+
${sudo} apt-get update -qq
|
|
183
|
+
${sudo} apt-get install -y --no-install-recommends \
|
|
155
184
|
pandoc \
|
|
156
185
|
texlive-latex-recommended \
|
|
157
186
|
texlive-latex-extra \
|
|
158
|
-
texlive-fonts-recommended
|
|
187
|
+
texlive-fonts-recommended \
|
|
188
|
+
lmodern
|
|
159
189
|
|
|
160
190
|
- name: Validate requirements
|
|
161
191
|
if: inputs.run-validate-requirements == 'true'
|
|
@@ -196,6 +226,7 @@ runs:
|
|
|
196
226
|
run: |
|
|
197
227
|
project-documentation-build-pdfs \
|
|
198
228
|
--version "${{ inputs.version }}" \
|
|
229
|
+
--name-prefix "${{ inputs.name-prefix }}" \
|
|
199
230
|
--output-dir "${{ inputs.output-dir }}" \
|
|
200
231
|
--docs-dirs ${{ inputs.docs-dirs }} \
|
|
201
232
|
--requirements-dir "${{ inputs.requirements-dir }}"
|
|
@@ -59,6 +59,7 @@ matrix.
|
|
|
59
59
|
| Input | Default | Description |
|
|
60
60
|
|-----------------|----------------------------------------------------------------------|-----------------------------------------------------|
|
|
61
61
|
| `version` | `""` | Release version used to name output files. |
|
|
62
|
+
| `name-prefix` | `""` | Prefix for every PDF file name, e.g. the project name (`my_project-design-x-v1.2.3.pdf`). |
|
|
62
63
|
| `output-dir` | `docs-pdf` | Output directory for PDFs. |
|
|
63
64
|
| `docs-dirs` | `documentation/architecture documentation/design documentation/theory` | Space-separated doc directories. |
|
|
64
65
|
| `requirements-dir` | `documentation/requirements` | Requirements dir (included as appendix). |
|
|
@@ -78,8 +79,8 @@ matrix.
|
|
|
78
79
|
|
|
79
80
|
| Input | Default | Description |
|
|
80
81
|
|------------------|----------|----------------------------------------------------------------------------------------|
|
|
81
|
-
| `python-version` | `3.11` | Python version to use.
|
|
82
|
-
| `package-version`| `""` | pip specifier for `project-documentation` (e.g. `==0.1.0`). Empty =
|
|
82
|
+
| `python-version` | `3.11` | Python version to set up. Empty = use the `python3` on the PATH (e.g. in a container). |
|
|
83
|
+
| `package-version`| `""` | pip specifier for `project-documentation` (e.g. `==0.1.0`). Empty = this action's own source, matching the pinned ref. |
|
|
83
84
|
|
|
84
85
|
---
|
|
85
86
|
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: FOC Architecture
|
|
3
|
+
type: architecture
|
|
4
|
+
status: draft
|
|
5
|
+
version: "1.0"
|
|
6
|
+
component: foc
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Assumptions & Constraints
|
|
10
|
+
|
|
11
|
+
No heap allocation. All buffers are statically allocated.
|
|
12
|
+
The FOC loop must complete within 400 cycles at 120 MHz.
|
|
13
|
+
|
|
14
|
+
## System Overview
|
|
15
|
+
|
|
16
|
+
Field-Oriented Control (FOC) provides independent torque and flux control
|
|
17
|
+
for BLDC/PMSM motors by transforming phase currents into a rotating frame
|
|
18
|
+
aligned with the rotor flux.
|
|
19
|
+
|
|
20
|
+
## Component Decomposition
|
|
21
|
+
|
|
22
|
+
- Clarke transform: converts 3-phase currents to alpha-beta frame
|
|
23
|
+
- Park transform: rotates to rotor-synchronous d-q frame
|
|
24
|
+
- PI controllers: independent Id and Iq regulators
|
|
25
|
+
- Inverse Park and SVM: reconstruct phase voltages
|
|
26
|
+
|
|
27
|
+
## Interfaces & Contracts
|
|
28
|
+
|
|
29
|
+
All interfaces are defined as pure abstract classes. Platform-specific
|
|
30
|
+
implementations are injected via the `PlatformFactory` interface.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Clarke Transform Design
|
|
3
|
+
type: design
|
|
4
|
+
status: approved
|
|
5
|
+
version: "1.0"
|
|
6
|
+
component: foc
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Responsibilities
|
|
10
|
+
|
|
11
|
+
Convert three-phase stator currents (ia, ib, ic) to the two-phase
|
|
12
|
+
stationary reference frame (alpha, beta) using the power-invariant form.
|
|
13
|
+
|
|
14
|
+
## Component Details
|
|
15
|
+
|
|
16
|
+
The Clarke transform is implemented as a static inline function operating
|
|
17
|
+
on Q31 fixed-point values. The coefficients are precomputed as compile-time
|
|
18
|
+
constants to avoid runtime division.
|
|
19
|
+
|
|
20
|
+
## Interfaces
|
|
21
|
+
|
|
22
|
+
Input: `ia`, `ib` (ic is derived from Kirchhoff's current law: ic = -ia - ib).
|
|
23
|
+
Output: `alpha = ia`, `beta = (ia + 2*ib) / sqrt(3)`.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
Feature: FOC current control
|
|
2
|
+
|
|
3
|
+
# REQ-FOC-001
|
|
4
|
+
Scenario: Independent Id and Iq control
|
|
5
|
+
Given a PMSM motor model running at steady state
|
|
6
|
+
When a d-axis current reference of 0 A is applied
|
|
7
|
+
And a q-axis current reference of 5 A is applied
|
|
8
|
+
Then the d-axis current converges to 0 A within 10 ms
|
|
9
|
+
And the q-axis current converges to 5 A within 10 ms
|
|
10
|
+
|
|
11
|
+
# REQ-FOC-002
|
|
12
|
+
Scenario: Clarke transform produces correct alpha-beta values
|
|
13
|
+
Given three-phase currents ia = 1.0 A, ib = -0.5 A, ic = -0.5 A
|
|
14
|
+
When the Clarke transform is applied
|
|
15
|
+
Then alpha = 1.0 A
|
|
16
|
+
And beta = 0.0 A
|
|
17
|
+
|
|
18
|
+
# REQ-FOC-003
|
|
19
|
+
Scenario: Park transform rotates correctly at known angle
|
|
20
|
+
Given stationary frame currents alpha = 1.0 A, beta = 0.0 A
|
|
21
|
+
And rotor electrical angle theta = 0 degrees
|
|
22
|
+
When the Park transform is applied
|
|
23
|
+
Then id = 1.0 A
|
|
24
|
+
And iq = 0.0 A
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "project-documentation"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.4.0"
|
|
8
8
|
description = "Documentation pipeline for embedded projects: validates requirements and design documents, generates PDFs, and produces a traceability matrix."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.11"
|
|
@@ -6,6 +6,7 @@ requirements to PDF using Pandoc.
|
|
|
6
6
|
Usage:
|
|
7
7
|
project-documentation-build-pdfs \\
|
|
8
8
|
--version v1.2.3 \\
|
|
9
|
+
--name-prefix my_project \\
|
|
9
10
|
--output-dir docs-pdf \\
|
|
10
11
|
--docs-dirs documentation/architecture documentation/design documentation/theory \\
|
|
11
12
|
--requirements-dir documentation/requirements
|
|
@@ -40,7 +41,11 @@ def _run_pandoc(output_path: Path, *input_paths: Path) -> bool:
|
|
|
40
41
|
return True
|
|
41
42
|
|
|
42
43
|
|
|
43
|
-
def
|
|
44
|
+
def _pdf_name(prefix: str, *parts: str) -> str:
|
|
45
|
+
return "-".join(part for part in (prefix, *parts) if part) + ".pdf"
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def convert_markdown_dirs(docs_dirs: list[str], version: str, output_dir: Path, prefix: str = "") -> None:
|
|
44
49
|
for docdir in docs_dirs:
|
|
45
50
|
path = Path(docdir)
|
|
46
51
|
if not path.is_dir():
|
|
@@ -48,7 +53,7 @@ def convert_markdown_dirs(docs_dirs: list[str], version: str, output_dir: Path)
|
|
|
48
53
|
category = path.name
|
|
49
54
|
for md in sorted(path.rglob("*.md")):
|
|
50
55
|
name = md.stem
|
|
51
|
-
out = output_dir /
|
|
56
|
+
out = output_dir / _pdf_name(prefix, category, name, version)
|
|
52
57
|
_run_pandoc(out, md)
|
|
53
58
|
|
|
54
59
|
|
|
@@ -63,7 +68,7 @@ def _requirement_to_markdown(req: dict[str, str]) -> str:
|
|
|
63
68
|
return "\n".join(lines)
|
|
64
69
|
|
|
65
70
|
|
|
66
|
-
def convert_requirements(requirements_dir: Path, version: str, output_dir: Path) -> None:
|
|
71
|
+
def convert_requirements(requirements_dir: Path, version: str, output_dir: Path, prefix: str = "") -> None:
|
|
67
72
|
yaml_files = sorted(requirements_dir.rglob("*.yaml"))
|
|
68
73
|
if not yaml_files:
|
|
69
74
|
print(f"INFO: No YAML files found in {requirements_dir}", file=sys.stderr)
|
|
@@ -85,13 +90,18 @@ def convert_requirements(requirements_dir: Path, version: str, output_dir: Path)
|
|
|
85
90
|
print("INFO: No requirements content to convert", file=sys.stderr)
|
|
86
91
|
return
|
|
87
92
|
|
|
88
|
-
out = output_dir /
|
|
93
|
+
out = output_dir / _pdf_name(prefix, "requirements", version)
|
|
89
94
|
_run_pandoc(out, *tmp_mds)
|
|
90
95
|
|
|
91
96
|
|
|
92
97
|
def main() -> int:
|
|
93
98
|
parser = argparse.ArgumentParser(description="Build documentation PDFs from Markdown and YAML requirements")
|
|
94
99
|
parser.add_argument("--version", required=True, help="Release version tag (e.g. v1.2.3)")
|
|
100
|
+
parser.add_argument(
|
|
101
|
+
"--name-prefix",
|
|
102
|
+
default="",
|
|
103
|
+
help="Prefix for every PDF file name, e.g. the project name (my_project-design-x-v1.2.3.pdf)",
|
|
104
|
+
)
|
|
95
105
|
parser.add_argument("--output-dir", default="docs-pdf", help="Output directory for PDFs")
|
|
96
106
|
parser.add_argument(
|
|
97
107
|
"--docs-dirs",
|
|
@@ -109,8 +119,8 @@ def main() -> int:
|
|
|
109
119
|
output_dir = Path(args.output_dir)
|
|
110
120
|
output_dir.mkdir(parents=True, exist_ok=True)
|
|
111
121
|
|
|
112
|
-
convert_markdown_dirs(args.docs_dirs, args.version, output_dir)
|
|
113
|
-
convert_requirements(Path(args.requirements_dir), args.version, output_dir)
|
|
122
|
+
convert_markdown_dirs(args.docs_dirs, args.version, output_dir, args.name_prefix)
|
|
123
|
+
convert_requirements(Path(args.requirements_dir), args.version, output_dir, args.name_prefix)
|
|
114
124
|
|
|
115
125
|
return 0
|
|
116
126
|
|
|
@@ -8,52 +8,54 @@ from pathlib import Path
|
|
|
8
8
|
import yaml
|
|
9
9
|
|
|
10
10
|
|
|
11
|
-
def
|
|
12
|
-
|
|
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"))
|
|
11
|
+
def _build_markdown(template_text: str, yaml_files: list[Path]) -> str:
|
|
12
|
+
"""Build a Markdown document from a template and YAML requirement files."""
|
|
23
13
|
sections: dict[str, list[dict[str, str]]] = {}
|
|
24
14
|
|
|
25
15
|
for yaml_file in yaml_files:
|
|
26
16
|
section = yaml_file.parent.name.replace("-", " ").replace("_", " ").title()
|
|
27
17
|
content = yaml.safe_load(yaml_file.read_text())
|
|
28
|
-
|
|
29
18
|
if content is None:
|
|
30
19
|
continue
|
|
20
|
+
sections.setdefault(section, []).extend(content)
|
|
31
21
|
|
|
32
|
-
|
|
33
|
-
sections[section] = []
|
|
34
|
-
sections[section].extend(content)
|
|
35
|
-
|
|
36
|
-
# Generate markdown for each section
|
|
22
|
+
markdown = template_text
|
|
37
23
|
for section, requirements in sorted(sections.items()):
|
|
38
24
|
markdown += f"\n## {section}\n\n"
|
|
39
|
-
|
|
40
25
|
for req in requirements:
|
|
41
26
|
markdown += f"### {req['id']}: {req['title']}\n\n"
|
|
42
27
|
markdown += f"{req['shall']}\n\n"
|
|
43
28
|
|
|
29
|
+
return markdown
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def main() -> None:
|
|
33
|
+
parser = argparse.ArgumentParser()
|
|
34
|
+
parser.add_argument("--requirements-dir", required=True, type=Path)
|
|
35
|
+
parser.add_argument("--template", required=True, type=Path)
|
|
36
|
+
parser.add_argument("--output", required=True, type=Path)
|
|
37
|
+
args = parser.parse_args()
|
|
38
|
+
|
|
39
|
+
yaml_files = sorted(args.requirements_dir.glob("**/*.yaml"))
|
|
40
|
+
markdown = _build_markdown(args.template.read_text(), yaml_files)
|
|
41
|
+
|
|
44
42
|
# Write intermediate markdown
|
|
45
43
|
md_path = args.output.with_suffix(".md")
|
|
46
44
|
md_path.parent.mkdir(parents=True, exist_ok=True)
|
|
47
45
|
md_path.write_text(markdown)
|
|
48
46
|
|
|
49
|
-
# Convert to PDF with pandoc
|
|
47
|
+
# Convert to PDF with pandoc (explicit engine for reproducibility)
|
|
50
48
|
args.output.parent.mkdir(parents=True, exist_ok=True)
|
|
51
|
-
subprocess.run(
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
49
|
+
subprocess.run(
|
|
50
|
+
[
|
|
51
|
+
"pandoc", str(md_path),
|
|
52
|
+
"-o", str(args.output),
|
|
53
|
+
"--pdf-engine=pdflatex",
|
|
54
|
+
"--toc",
|
|
55
|
+
"-V", "geometry:margin=1in",
|
|
56
|
+
],
|
|
57
|
+
check=True,
|
|
58
|
+
)
|
|
57
59
|
|
|
58
60
|
print(f"✓ Generated {args.output}")
|
|
59
61
|
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Package marker for integration tests."""
|
|
@@ -0,0 +1,357 @@
|
|
|
1
|
+
"""Integration tests — exercise real CLI entry points end-to-end.
|
|
2
|
+
|
|
3
|
+
These tests call the installed CLI commands via subprocess so they exercise
|
|
4
|
+
the full path from argument parsing through file I/O. PDF-generating tests
|
|
5
|
+
are skipped when pandoc is not available in the environment.
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import shutil
|
|
10
|
+
import subprocess
|
|
11
|
+
import sys
|
|
12
|
+
import textwrap
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
|
|
15
|
+
import pytest
|
|
16
|
+
import yaml
|
|
17
|
+
|
|
18
|
+
# ── helpers ───────────────────────────────────────────────────────────────────
|
|
19
|
+
|
|
20
|
+
def _run(cmd: list[str]) -> subprocess.CompletedProcess[str]:
|
|
21
|
+
return subprocess.run(cmd, capture_output=True, text=True)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _write_yaml(path: Path, content: object) -> None:
|
|
25
|
+
path.write_text(yaml.dump(content))
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _write_text(path: Path, content: str) -> None:
|
|
29
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
30
|
+
path.write_text(textwrap.dedent(content))
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
_PANDOC_AVAILABLE = shutil.which("pandoc") is not None
|
|
34
|
+
_skip_no_pandoc = pytest.mark.skipif(not _PANDOC_AVAILABLE, reason="pandoc not installed")
|
|
35
|
+
|
|
36
|
+
# ── validate-requirements ─────────────────────────────────────────────────────
|
|
37
|
+
|
|
38
|
+
class TestValidateRequirementsCLI:
|
|
39
|
+
@pytest.fixture()
|
|
40
|
+
def req_env(self, tmp_path: Path) -> dict[str, Path]:
|
|
41
|
+
req_dir = tmp_path / "requirements"
|
|
42
|
+
req_dir.mkdir()
|
|
43
|
+
schema = tmp_path / "requirement.schema.json"
|
|
44
|
+
schema.write_text(
|
|
45
|
+
'{"type":"array","items":{"type":"object","required":["id","title","shall"],'
|
|
46
|
+
'"properties":{"id":{"type":"string"},"title":{"type":"string"},"shall":{"type":"string"}},'
|
|
47
|
+
'"additionalProperties":false}}'
|
|
48
|
+
)
|
|
49
|
+
_write_yaml(
|
|
50
|
+
req_dir / "foc.yaml",
|
|
51
|
+
[{"id": "REQ-FOC-001", "title": "Clarke", "shall": "The system shall..."}],
|
|
52
|
+
)
|
|
53
|
+
return {"req_dir": req_dir, "schema": schema}
|
|
54
|
+
|
|
55
|
+
def test_valid_requirements_exits_zero(self, req_env: dict[str, Path]) -> None:
|
|
56
|
+
result = _run(
|
|
57
|
+
[
|
|
58
|
+
sys.executable, "-m", "project_documentation.validate_requirements",
|
|
59
|
+
"--schema", str(req_env["schema"]),
|
|
60
|
+
"--requirements-dir", str(req_env["req_dir"]),
|
|
61
|
+
]
|
|
62
|
+
)
|
|
63
|
+
assert result.returncode == 0
|
|
64
|
+
assert "✓" in result.stdout
|
|
65
|
+
|
|
66
|
+
def test_invalid_requirement_exits_nonzero(self, req_env: dict[str, Path]) -> None:
|
|
67
|
+
_write_yaml(
|
|
68
|
+
req_env["req_dir"] / "bad.yaml",
|
|
69
|
+
[{"id": "REQ-001", "unknown_field": "oops"}],
|
|
70
|
+
)
|
|
71
|
+
result = _run(
|
|
72
|
+
[
|
|
73
|
+
sys.executable, "-m", "project_documentation.validate_requirements",
|
|
74
|
+
"--schema", str(req_env["schema"]),
|
|
75
|
+
"--requirements-dir", str(req_env["req_dir"]),
|
|
76
|
+
]
|
|
77
|
+
)
|
|
78
|
+
assert result.returncode == 1
|
|
79
|
+
assert "✗" in result.stdout
|
|
80
|
+
|
|
81
|
+
def test_empty_dir_exits_zero(self, tmp_path: Path) -> None:
|
|
82
|
+
req_dir = tmp_path / "empty"
|
|
83
|
+
req_dir.mkdir()
|
|
84
|
+
schema = tmp_path / "s.json"
|
|
85
|
+
schema.write_text('{"type":"array","items":{"type":"object"}}')
|
|
86
|
+
result = _run(
|
|
87
|
+
[
|
|
88
|
+
sys.executable, "-m", "project_documentation.validate_requirements",
|
|
89
|
+
"--schema", str(schema),
|
|
90
|
+
"--requirements-dir", str(req_dir),
|
|
91
|
+
]
|
|
92
|
+
)
|
|
93
|
+
assert result.returncode == 0
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
# ── validate-documents ────────────────────────────────────────────────────────
|
|
97
|
+
|
|
98
|
+
class TestValidateDocumentsCLI:
|
|
99
|
+
_VALID_ARCHITECTURE = textwrap.dedent("""\
|
|
100
|
+
---
|
|
101
|
+
title: FOC Architecture
|
|
102
|
+
type: architecture
|
|
103
|
+
status: draft
|
|
104
|
+
version: "1.0"
|
|
105
|
+
component: foc
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## Assumptions & Constraints
|
|
109
|
+
No heap.
|
|
110
|
+
|
|
111
|
+
## System Overview
|
|
112
|
+
Overview.
|
|
113
|
+
|
|
114
|
+
## Component Decomposition
|
|
115
|
+
- Clarke
|
|
116
|
+
- Park
|
|
117
|
+
|
|
118
|
+
## Interfaces & Contracts
|
|
119
|
+
All pure virtual.
|
|
120
|
+
""")
|
|
121
|
+
|
|
122
|
+
def test_valid_architecture_exits_zero(self, tmp_path: Path) -> None:
|
|
123
|
+
_write_text(tmp_path / "arch.md", self._VALID_ARCHITECTURE)
|
|
124
|
+
result = _run(
|
|
125
|
+
[
|
|
126
|
+
sys.executable, "-m", "project_documentation.validate_documents",
|
|
127
|
+
"--documents-dir", str(tmp_path),
|
|
128
|
+
"--doc-type", "architecture",
|
|
129
|
+
]
|
|
130
|
+
)
|
|
131
|
+
assert result.returncode == 0
|
|
132
|
+
|
|
133
|
+
def test_forbidden_code_block_exits_nonzero(self, tmp_path: Path) -> None:
|
|
134
|
+
doc = self._VALID_ARCHITECTURE + "\n```cpp\nvoid foo(){}\n```\n"
|
|
135
|
+
_write_text(tmp_path / "doc.md", doc)
|
|
136
|
+
result = _run(
|
|
137
|
+
[
|
|
138
|
+
sys.executable, "-m", "project_documentation.validate_documents",
|
|
139
|
+
"--documents-dir", str(tmp_path),
|
|
140
|
+
"--doc-type", "architecture",
|
|
141
|
+
]
|
|
142
|
+
)
|
|
143
|
+
assert result.returncode == 1
|
|
144
|
+
|
|
145
|
+
def test_missing_section_exits_nonzero(self, tmp_path: Path) -> None:
|
|
146
|
+
doc = textwrap.dedent("""\
|
|
147
|
+
---
|
|
148
|
+
title: Incomplete
|
|
149
|
+
type: architecture
|
|
150
|
+
status: draft
|
|
151
|
+
version: "1.0"
|
|
152
|
+
component: foc
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## Assumptions & Constraints
|
|
156
|
+
Only one section.
|
|
157
|
+
""")
|
|
158
|
+
_write_text(tmp_path / "incomplete.md", doc)
|
|
159
|
+
result = _run(
|
|
160
|
+
[
|
|
161
|
+
sys.executable, "-m", "project_documentation.validate_documents",
|
|
162
|
+
"--documents-dir", str(tmp_path),
|
|
163
|
+
"--doc-type", "architecture",
|
|
164
|
+
]
|
|
165
|
+
)
|
|
166
|
+
assert result.returncode == 1
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
# ── generate-traceability-matrix ──────────────────────────────────────────────
|
|
170
|
+
|
|
171
|
+
class TestTraceabilityMatrixCLI:
|
|
172
|
+
def test_generates_matrix_markdown(self, tmp_path: Path) -> None:
|
|
173
|
+
req_dir = tmp_path / "requirements"
|
|
174
|
+
req_dir.mkdir()
|
|
175
|
+
_write_yaml(
|
|
176
|
+
req_dir / "foc.yaml",
|
|
177
|
+
[{"id": "REQ-FOC-001", "title": "Clarke", "shall": "..."}],
|
|
178
|
+
)
|
|
179
|
+
features_dir = tmp_path / "features"
|
|
180
|
+
features_dir.mkdir()
|
|
181
|
+
(features_dir / "foc.feature").write_text(
|
|
182
|
+
"Feature: FOC\n # REQ-FOC-001\n Scenario: Clarke works\n Given ...\n"
|
|
183
|
+
)
|
|
184
|
+
output = tmp_path / "matrix.md"
|
|
185
|
+
|
|
186
|
+
result = _run(
|
|
187
|
+
[
|
|
188
|
+
sys.executable, "-m", "project_documentation.generate_traceability_matrix",
|
|
189
|
+
"--requirements-dir", str(req_dir),
|
|
190
|
+
"--features-dir", str(features_dir),
|
|
191
|
+
"--output", str(output),
|
|
192
|
+
]
|
|
193
|
+
)
|
|
194
|
+
assert result.returncode == 0
|
|
195
|
+
assert output.exists()
|
|
196
|
+
content = output.read_text()
|
|
197
|
+
assert "REQ-FOC-001" in content
|
|
198
|
+
assert "Clarke works" in content
|
|
199
|
+
|
|
200
|
+
def test_uncovered_requirement_listed(self, tmp_path: Path) -> None:
|
|
201
|
+
req_dir = tmp_path / "requirements"
|
|
202
|
+
req_dir.mkdir()
|
|
203
|
+
_write_yaml(
|
|
204
|
+
req_dir / "foc.yaml",
|
|
205
|
+
[{"id": "REQ-FOC-001", "title": "Uncovered", "shall": "..."}],
|
|
206
|
+
)
|
|
207
|
+
features_dir = tmp_path / "features"
|
|
208
|
+
features_dir.mkdir()
|
|
209
|
+
output = tmp_path / "matrix.md"
|
|
210
|
+
|
|
211
|
+
result = _run(
|
|
212
|
+
[
|
|
213
|
+
sys.executable, "-m", "project_documentation.generate_traceability_matrix",
|
|
214
|
+
"--requirements-dir", str(req_dir),
|
|
215
|
+
"--features-dir", str(features_dir),
|
|
216
|
+
"--output", str(output),
|
|
217
|
+
]
|
|
218
|
+
)
|
|
219
|
+
assert result.returncode == 0
|
|
220
|
+
assert "Uncovered Requirements" in output.read_text()
|
|
221
|
+
|
|
222
|
+
def test_coverage_summary_shows_percentage(self, tmp_path: Path) -> None:
|
|
223
|
+
req_dir = tmp_path / "requirements"
|
|
224
|
+
req_dir.mkdir()
|
|
225
|
+
_write_yaml(req_dir / "foc.yaml", [{"id": "REQ-FOC-001", "title": "T", "shall": "S"}])
|
|
226
|
+
features_dir = tmp_path / "features"
|
|
227
|
+
features_dir.mkdir()
|
|
228
|
+
(features_dir / "foc.feature").write_text(
|
|
229
|
+
"Feature: F\n # REQ-FOC-001\n Scenario: S1\n Given ...\n"
|
|
230
|
+
)
|
|
231
|
+
output = tmp_path / "matrix.md"
|
|
232
|
+
_run(
|
|
233
|
+
[
|
|
234
|
+
sys.executable, "-m", "project_documentation.generate_traceability_matrix",
|
|
235
|
+
"--requirements-dir", str(req_dir),
|
|
236
|
+
"--features-dir", str(features_dir),
|
|
237
|
+
"--output", str(output),
|
|
238
|
+
]
|
|
239
|
+
)
|
|
240
|
+
assert "100%" in output.read_text()
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
# ── generate-requirements-pdf ─────────────────────────────────────────────────
|
|
244
|
+
|
|
245
|
+
@_skip_no_pandoc
|
|
246
|
+
class TestGenerateRequirementsPDFCLI:
|
|
247
|
+
def test_generates_pdf_and_intermediate_md(self, tmp_path: Path) -> None:
|
|
248
|
+
req_dir = tmp_path / "requirements"
|
|
249
|
+
req_dir.mkdir()
|
|
250
|
+
_write_yaml(
|
|
251
|
+
req_dir / "foc.yaml",
|
|
252
|
+
[{"id": "REQ-FOC-001", "title": "Clarke transform", "shall": "The system shall..."}],
|
|
253
|
+
)
|
|
254
|
+
template = tmp_path / "template.md"
|
|
255
|
+
template.write_text("# Requirements\n\n")
|
|
256
|
+
output = tmp_path / "out" / "requirements.pdf"
|
|
257
|
+
|
|
258
|
+
result = _run(
|
|
259
|
+
[
|
|
260
|
+
sys.executable, "-m", "project_documentation.generate_requirements_pdf",
|
|
261
|
+
"--requirements-dir", str(req_dir),
|
|
262
|
+
"--template", str(template),
|
|
263
|
+
"--output", str(output),
|
|
264
|
+
]
|
|
265
|
+
)
|
|
266
|
+
assert result.returncode == 0, result.stderr
|
|
267
|
+
assert output.exists()
|
|
268
|
+
assert output.with_suffix(".md").exists()
|
|
269
|
+
|
|
270
|
+
def test_intermediate_markdown_contains_requirements(self, tmp_path: Path) -> None:
|
|
271
|
+
req_dir = tmp_path / "requirements"
|
|
272
|
+
req_dir.mkdir()
|
|
273
|
+
_write_yaml(
|
|
274
|
+
req_dir / "foc.yaml",
|
|
275
|
+
[{"id": "REQ-001", "title": "My Title", "shall": "The system shall do X."}],
|
|
276
|
+
)
|
|
277
|
+
template = tmp_path / "template.md"
|
|
278
|
+
template.write_text("# Header\n\n")
|
|
279
|
+
output = tmp_path / "out.pdf"
|
|
280
|
+
|
|
281
|
+
_run(
|
|
282
|
+
[
|
|
283
|
+
sys.executable, "-m", "project_documentation.generate_requirements_pdf",
|
|
284
|
+
"--requirements-dir", str(req_dir),
|
|
285
|
+
"--template", str(template),
|
|
286
|
+
"--output", str(output),
|
|
287
|
+
]
|
|
288
|
+
)
|
|
289
|
+
md = output.with_suffix(".md").read_text()
|
|
290
|
+
assert "REQ-001" in md
|
|
291
|
+
assert "My Title" in md
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
# ── build-documentation-pdfs ──────────────────────────────────────────────────
|
|
295
|
+
|
|
296
|
+
@_skip_no_pandoc
|
|
297
|
+
class TestBuildDocumentationPDFsCLI:
|
|
298
|
+
_VALID_THEORY = textwrap.dedent("""\
|
|
299
|
+
---
|
|
300
|
+
title: FOC Theory
|
|
301
|
+
type: theory
|
|
302
|
+
status: approved
|
|
303
|
+
version: "1.0"
|
|
304
|
+
component: foc
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## Overview
|
|
308
|
+
FOC overview.
|
|
309
|
+
|
|
310
|
+
## Mathematical Foundation
|
|
311
|
+
$i_d = i_s \\cos\\theta$
|
|
312
|
+
|
|
313
|
+
## Numerical Properties
|
|
314
|
+
Q15 fixed-point.
|
|
315
|
+
""")
|
|
316
|
+
|
|
317
|
+
def test_generates_pdf_from_markdown(self, tmp_path: Path) -> None:
|
|
318
|
+
docs_dir = tmp_path / "theory"
|
|
319
|
+
docs_dir.mkdir()
|
|
320
|
+
_write_text(docs_dir / "foc.md", self._VALID_THEORY)
|
|
321
|
+
req_dir = tmp_path / "requirements"
|
|
322
|
+
req_dir.mkdir()
|
|
323
|
+
output_dir = tmp_path / "out"
|
|
324
|
+
|
|
325
|
+
result = _run(
|
|
326
|
+
[
|
|
327
|
+
sys.executable, "-m", "project_documentation.build_documentation_pdfs",
|
|
328
|
+
"--version", "v1.0",
|
|
329
|
+
"--output-dir", str(output_dir),
|
|
330
|
+
"--docs-dirs", str(docs_dir),
|
|
331
|
+
"--requirements-dir", str(req_dir),
|
|
332
|
+
]
|
|
333
|
+
)
|
|
334
|
+
assert result.returncode == 0, result.stderr
|
|
335
|
+
pdfs = list(output_dir.glob("*.pdf"))
|
|
336
|
+
assert len(pdfs) >= 1
|
|
337
|
+
assert any("theory-foc-v1.0.pdf" in p.name for p in pdfs)
|
|
338
|
+
|
|
339
|
+
def test_output_filenames_have_no_e_foc_prefix(self, tmp_path: Path) -> None:
|
|
340
|
+
docs_dir = tmp_path / "design"
|
|
341
|
+
docs_dir.mkdir()
|
|
342
|
+
_write_text(docs_dir / "clarke.md", "# Clarke\n\nDesign.")
|
|
343
|
+
req_dir = tmp_path / "requirements"
|
|
344
|
+
req_dir.mkdir()
|
|
345
|
+
output_dir = tmp_path / "out"
|
|
346
|
+
|
|
347
|
+
_run(
|
|
348
|
+
[
|
|
349
|
+
sys.executable, "-m", "project_documentation.build_documentation_pdfs",
|
|
350
|
+
"--version", "v2.0",
|
|
351
|
+
"--output-dir", str(output_dir),
|
|
352
|
+
"--docs-dirs", str(docs_dir),
|
|
353
|
+
"--requirements-dir", str(req_dir),
|
|
354
|
+
]
|
|
355
|
+
)
|
|
356
|
+
for pdf in output_dir.glob("*.pdf"):
|
|
357
|
+
assert not pdf.name.startswith("e_foc"), f"Unexpected e_foc prefix: {pdf.name}"
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
"""Unit tests for build_documentation_pdfs."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from unittest.mock import patch
|
|
6
|
+
|
|
7
|
+
import pytest
|
|
8
|
+
import yaml
|
|
9
|
+
|
|
10
|
+
from project_documentation.build_documentation_pdfs import (
|
|
11
|
+
_requirement_to_markdown,
|
|
12
|
+
convert_markdown_dirs,
|
|
13
|
+
convert_requirements,
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _write_yaml(path: Path, content: object) -> None:
|
|
18
|
+
path.write_text(yaml.dump(content))
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class TestRequirementToMarkdown:
|
|
22
|
+
def test_full_requirement(self) -> None:
|
|
23
|
+
req = {"id": "REQ-FOC-001", "title": "Clarke transform", "shall": "The system shall..."}
|
|
24
|
+
md = _requirement_to_markdown(req)
|
|
25
|
+
assert "## REQ-FOC-001: Clarke transform" in md
|
|
26
|
+
assert "The system shall..." in md
|
|
27
|
+
|
|
28
|
+
def test_missing_fields_produce_empty_strings(self) -> None:
|
|
29
|
+
md = _requirement_to_markdown({})
|
|
30
|
+
assert "## :" in md # empty id: empty title
|
|
31
|
+
|
|
32
|
+
def test_no_shall_omits_body(self) -> None:
|
|
33
|
+
md = _requirement_to_markdown({"id": "REQ-001", "title": "T", "shall": ""})
|
|
34
|
+
assert "REQ-001" in md
|
|
35
|
+
lines = [ln for ln in md.splitlines() if ln.strip()]
|
|
36
|
+
assert len(lines) == 1 # only the heading
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class TestConvertMarkdownDirs:
|
|
40
|
+
def test_converts_md_files_in_dir(self, tmp_path: Path) -> None:
|
|
41
|
+
docs_dir = tmp_path / "architecture"
|
|
42
|
+
docs_dir.mkdir()
|
|
43
|
+
(docs_dir / "overview.md").write_text("# Overview\n")
|
|
44
|
+
output_dir = tmp_path / "out"
|
|
45
|
+
output_dir.mkdir()
|
|
46
|
+
|
|
47
|
+
with patch(
|
|
48
|
+
"project_documentation.build_documentation_pdfs._run_pandoc",
|
|
49
|
+
return_value=True,
|
|
50
|
+
) as mock_pandoc:
|
|
51
|
+
convert_markdown_dirs([str(docs_dir)], "v1.0", output_dir)
|
|
52
|
+
|
|
53
|
+
assert mock_pandoc.call_count == 1
|
|
54
|
+
out_path = mock_pandoc.call_args[0][0]
|
|
55
|
+
assert "architecture-overview-v1.0.pdf" in str(out_path)
|
|
56
|
+
|
|
57
|
+
def test_no_e_foc_prefix_in_output(self, tmp_path: Path) -> None:
|
|
58
|
+
docs_dir = tmp_path / "design"
|
|
59
|
+
docs_dir.mkdir()
|
|
60
|
+
(docs_dir / "foc.md").write_text("# FOC\n")
|
|
61
|
+
output_dir = tmp_path / "out"
|
|
62
|
+
output_dir.mkdir()
|
|
63
|
+
|
|
64
|
+
with patch(
|
|
65
|
+
"project_documentation.build_documentation_pdfs._run_pandoc",
|
|
66
|
+
return_value=True,
|
|
67
|
+
) as mock_pandoc:
|
|
68
|
+
convert_markdown_dirs([str(docs_dir)], "v2.0", output_dir)
|
|
69
|
+
|
|
70
|
+
out_path = mock_pandoc.call_args[0][0]
|
|
71
|
+
assert not out_path.name.startswith("e_foc"), f"Unexpected e_foc prefix: {out_path.name}"
|
|
72
|
+
assert out_path.name == "design-foc-v2.0.pdf"
|
|
73
|
+
|
|
74
|
+
def test_name_prefix_leads_the_file_name(self, tmp_path: Path) -> None:
|
|
75
|
+
docs_dir = tmp_path / "design"
|
|
76
|
+
docs_dir.mkdir()
|
|
77
|
+
(docs_dir / "safety.md").write_text("# Safety\n")
|
|
78
|
+
output_dir = tmp_path / "out"
|
|
79
|
+
output_dir.mkdir()
|
|
80
|
+
|
|
81
|
+
with patch(
|
|
82
|
+
"project_documentation.build_documentation_pdfs._run_pandoc",
|
|
83
|
+
return_value=True,
|
|
84
|
+
) as mock_pandoc:
|
|
85
|
+
convert_markdown_dirs([str(docs_dir)], "v1.0.1", output_dir, "my_project")
|
|
86
|
+
|
|
87
|
+
assert mock_pandoc.call_args[0][0].name == "my_project-design-safety-v1.0.1.pdf"
|
|
88
|
+
|
|
89
|
+
def test_missing_dir_is_skipped(self, tmp_path: Path) -> None:
|
|
90
|
+
output_dir = tmp_path / "out"
|
|
91
|
+
output_dir.mkdir()
|
|
92
|
+
with patch(
|
|
93
|
+
"project_documentation.build_documentation_pdfs._run_pandoc"
|
|
94
|
+
) as mock_pandoc:
|
|
95
|
+
convert_markdown_dirs([str(tmp_path / "nonexistent")], "v1.0", output_dir)
|
|
96
|
+
mock_pandoc.assert_not_called()
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
class TestConvertRequirements:
|
|
100
|
+
def test_produces_requirements_pdf(self, tmp_path: Path) -> None:
|
|
101
|
+
req_dir = tmp_path / "requirements"
|
|
102
|
+
req_dir.mkdir()
|
|
103
|
+
_write_yaml(
|
|
104
|
+
req_dir / "foc.yaml",
|
|
105
|
+
[{"id": "REQ-FOC-001", "title": "Clarke", "shall": "The system shall..."}],
|
|
106
|
+
)
|
|
107
|
+
output_dir = tmp_path / "out"
|
|
108
|
+
output_dir.mkdir()
|
|
109
|
+
|
|
110
|
+
with patch(
|
|
111
|
+
"project_documentation.build_documentation_pdfs._run_pandoc",
|
|
112
|
+
return_value=True,
|
|
113
|
+
) as mock_pandoc:
|
|
114
|
+
convert_requirements(req_dir, "v1.2", output_dir)
|
|
115
|
+
|
|
116
|
+
assert mock_pandoc.call_count == 1
|
|
117
|
+
out_path = str(mock_pandoc.call_args[0][0])
|
|
118
|
+
assert "requirements-v1.2.pdf" in out_path
|
|
119
|
+
assert "e_foc" not in out_path
|
|
120
|
+
|
|
121
|
+
def test_name_prefix_leads_the_file_name(self, tmp_path: Path) -> None:
|
|
122
|
+
req_dir = tmp_path / "requirements"
|
|
123
|
+
req_dir.mkdir()
|
|
124
|
+
_write_yaml(req_dir / "arm.yaml", [{"id": "REQ-ARM-001", "title": "T", "shall": "S"}])
|
|
125
|
+
output_dir = tmp_path / "out"
|
|
126
|
+
output_dir.mkdir()
|
|
127
|
+
|
|
128
|
+
with patch(
|
|
129
|
+
"project_documentation.build_documentation_pdfs._run_pandoc",
|
|
130
|
+
return_value=True,
|
|
131
|
+
) as mock_pandoc:
|
|
132
|
+
convert_requirements(req_dir, "v1.0.1", output_dir, "my_project")
|
|
133
|
+
|
|
134
|
+
assert mock_pandoc.call_args[0][0].name == "my_project-requirements-v1.0.1.pdf"
|
|
135
|
+
|
|
136
|
+
def test_empty_requirements_dir_skips_pandoc(
|
|
137
|
+
self, tmp_path: Path, capsys: pytest.CaptureFixture[str]
|
|
138
|
+
) -> None:
|
|
139
|
+
req_dir = tmp_path / "requirements"
|
|
140
|
+
req_dir.mkdir()
|
|
141
|
+
output_dir = tmp_path / "out"
|
|
142
|
+
output_dir.mkdir()
|
|
143
|
+
|
|
144
|
+
with patch(
|
|
145
|
+
"project_documentation.build_documentation_pdfs._run_pandoc"
|
|
146
|
+
) as mock_pandoc:
|
|
147
|
+
convert_requirements(req_dir, "v1.0", output_dir)
|
|
148
|
+
|
|
149
|
+
mock_pandoc.assert_not_called()
|
|
150
|
+
|
|
151
|
+
def test_non_list_yaml_is_skipped(self, tmp_path: Path) -> None:
|
|
152
|
+
req_dir = tmp_path / "requirements"
|
|
153
|
+
req_dir.mkdir()
|
|
154
|
+
(req_dir / "bad.yaml").write_text("key: value\n")
|
|
155
|
+
output_dir = tmp_path / "out"
|
|
156
|
+
output_dir.mkdir()
|
|
157
|
+
|
|
158
|
+
with patch(
|
|
159
|
+
"project_documentation.build_documentation_pdfs._run_pandoc"
|
|
160
|
+
) as mock_pandoc:
|
|
161
|
+
convert_requirements(req_dir, "v1.0", output_dir)
|
|
162
|
+
|
|
163
|
+
mock_pandoc.assert_not_called()
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
"""Unit tests for generate_requirements_pdf._build_markdown."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from unittest.mock import MagicMock, patch
|
|
6
|
+
|
|
7
|
+
import pytest
|
|
8
|
+
import yaml
|
|
9
|
+
|
|
10
|
+
from project_documentation.generate_requirements_pdf import _build_markdown, main
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def _write_yaml(directory: Path, name: str, content: object) -> None:
|
|
14
|
+
(directory / name).write_text(yaml.dump(content))
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class TestBuildMarkdown:
|
|
18
|
+
def test_prepends_template(self, tmp_path: Path) -> None:
|
|
19
|
+
req_dir = tmp_path / "reqs"
|
|
20
|
+
req_dir.mkdir()
|
|
21
|
+
_write_yaml(
|
|
22
|
+
req_dir,
|
|
23
|
+
"foc.yaml",
|
|
24
|
+
[{"id": "REQ-FOC-001", "title": "Clarke", "shall": "The system shall..."}],
|
|
25
|
+
)
|
|
26
|
+
md = _build_markdown("# Header\n\n", list(req_dir.glob("*.yaml")))
|
|
27
|
+
assert md.startswith("# Header\n\n")
|
|
28
|
+
|
|
29
|
+
def test_section_title_from_parent_dir(self, tmp_path: Path) -> None:
|
|
30
|
+
sub = tmp_path / "foc-control"
|
|
31
|
+
sub.mkdir()
|
|
32
|
+
_write_yaml(
|
|
33
|
+
sub,
|
|
34
|
+
"req.yaml",
|
|
35
|
+
[{"id": "REQ-001", "title": "T", "shall": "S"}],
|
|
36
|
+
)
|
|
37
|
+
md = _build_markdown("", list(sub.glob("*.yaml")))
|
|
38
|
+
assert "## Foc Control" in md
|
|
39
|
+
|
|
40
|
+
def test_requirement_heading_and_body(self, tmp_path: Path) -> None:
|
|
41
|
+
req_dir = tmp_path / "reqs"
|
|
42
|
+
req_dir.mkdir()
|
|
43
|
+
_write_yaml(
|
|
44
|
+
req_dir,
|
|
45
|
+
"reqs.yaml",
|
|
46
|
+
[{"id": "REQ-001", "title": "My Title", "shall": "The system shall do X."}],
|
|
47
|
+
)
|
|
48
|
+
md = _build_markdown("", list(req_dir.glob("*.yaml")))
|
|
49
|
+
assert "### REQ-001: My Title" in md
|
|
50
|
+
assert "The system shall do X." in md
|
|
51
|
+
|
|
52
|
+
def test_empty_yaml_file_is_skipped(self, tmp_path: Path) -> None:
|
|
53
|
+
req_dir = tmp_path / "reqs"
|
|
54
|
+
req_dir.mkdir()
|
|
55
|
+
(req_dir / "empty.yaml").write_text("")
|
|
56
|
+
md = _build_markdown("template\n", list(req_dir.glob("*.yaml")))
|
|
57
|
+
assert md == "template\n"
|
|
58
|
+
|
|
59
|
+
def test_multiple_files_sorted_by_section(self, tmp_path: Path) -> None:
|
|
60
|
+
for name in ("z-module", "a-module"):
|
|
61
|
+
sub = tmp_path / name
|
|
62
|
+
sub.mkdir()
|
|
63
|
+
_write_yaml(sub, "r.yaml", [{"id": f"REQ-{name}", "title": "T", "shall": "S"}])
|
|
64
|
+
files = sorted(tmp_path.rglob("*.yaml"))
|
|
65
|
+
md = _build_markdown("", files)
|
|
66
|
+
a_pos = md.index("A Module")
|
|
67
|
+
z_pos = md.index("Z Module")
|
|
68
|
+
assert a_pos < z_pos
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class TestMain:
|
|
72
|
+
def test_calls_pandoc_with_pdflatex(
|
|
73
|
+
self,
|
|
74
|
+
tmp_path: Path,
|
|
75
|
+
monkeypatch: pytest.MonkeyPatch,
|
|
76
|
+
) -> None:
|
|
77
|
+
req_dir = tmp_path / "reqs"
|
|
78
|
+
req_dir.mkdir()
|
|
79
|
+
_write_yaml(
|
|
80
|
+
req_dir,
|
|
81
|
+
"foc.yaml",
|
|
82
|
+
[{"id": "REQ-001", "title": "T", "shall": "S"}],
|
|
83
|
+
)
|
|
84
|
+
template = tmp_path / "template.md"
|
|
85
|
+
template.write_text("# Requirements\n\n")
|
|
86
|
+
output = tmp_path / "out" / "requirements.pdf"
|
|
87
|
+
|
|
88
|
+
monkeypatch.setattr(
|
|
89
|
+
"sys.argv",
|
|
90
|
+
[
|
|
91
|
+
"prog",
|
|
92
|
+
"--requirements-dir", str(req_dir),
|
|
93
|
+
"--template", str(template),
|
|
94
|
+
"--output", str(output),
|
|
95
|
+
],
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
mock_run = MagicMock(return_value=MagicMock(returncode=0))
|
|
99
|
+
with patch("subprocess.run", mock_run):
|
|
100
|
+
main()
|
|
101
|
+
|
|
102
|
+
assert mock_run.called
|
|
103
|
+
cmd = mock_run.call_args[0][0]
|
|
104
|
+
assert "pandoc" in cmd
|
|
105
|
+
assert "--pdf-engine=pdflatex" in cmd
|
|
106
|
+
assert str(output) in cmd
|
|
107
|
+
|
|
108
|
+
def test_intermediate_markdown_written(
|
|
109
|
+
self,
|
|
110
|
+
tmp_path: Path,
|
|
111
|
+
monkeypatch: pytest.MonkeyPatch,
|
|
112
|
+
) -> None:
|
|
113
|
+
req_dir = tmp_path / "reqs"
|
|
114
|
+
req_dir.mkdir()
|
|
115
|
+
_write_yaml(req_dir, "foc.yaml", [{"id": "REQ-001", "title": "T", "shall": "S"}])
|
|
116
|
+
template = tmp_path / "tmpl.md"
|
|
117
|
+
template.write_text("# Header\n")
|
|
118
|
+
output = tmp_path / "out.pdf"
|
|
119
|
+
|
|
120
|
+
monkeypatch.setattr(
|
|
121
|
+
"sys.argv",
|
|
122
|
+
["prog", "--requirements-dir", str(req_dir), "--template", str(template), "--output", str(output)],
|
|
123
|
+
)
|
|
124
|
+
|
|
125
|
+
with patch("subprocess.run", MagicMock()):
|
|
126
|
+
main()
|
|
127
|
+
|
|
128
|
+
md_path = output.with_suffix(".md")
|
|
129
|
+
assert md_path.exists()
|
|
130
|
+
content = md_path.read_text()
|
|
131
|
+
assert "# Header" in content
|
|
132
|
+
assert "REQ-001" in content
|
|
@@ -1,34 +0,0 @@
|
|
|
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
|
|
File without changes
|
|
File without changes
|
{project_documentation-0.2.0 → project_documentation-0.4.0}/examples/e-foc/documentation/theory.md
RENAMED
|
File without changes
|
{project_documentation-0.2.0 → project_documentation-0.4.0}/examples/e-foc/requirement.schema.json
RENAMED
|
File without changes
|
{project_documentation-0.2.0 → project_documentation-0.4.0}/examples/e-foc/requirements/foc.yaml
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{project_documentation-0.2.0 → project_documentation-0.4.0}/tests/unit/test_validate_documents.py
RENAMED
|
File without changes
|
{project_documentation-0.2.0 → project_documentation-0.4.0}/tests/unit/test_validate_requirements.py
RENAMED
|
File without changes
|