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.
Files changed (31) hide show
  1. project_documentation-0.4.0/CHANGELOG.md +65 -0
  2. {project_documentation-0.2.0 → project_documentation-0.4.0}/PKG-INFO +5 -3
  3. {project_documentation-0.2.0 → project_documentation-0.4.0}/README.md +3 -1
  4. {project_documentation-0.2.0 → project_documentation-0.4.0}/action.yml +38 -7
  5. {project_documentation-0.2.0 → project_documentation-0.4.0}/docs/usage.md +3 -2
  6. project_documentation-0.4.0/examples/e-foc/documentation/architecture.md +30 -0
  7. project_documentation-0.4.0/examples/e-foc/documentation/design.md +23 -0
  8. project_documentation-0.4.0/examples/e-foc/features/foc.feature +24 -0
  9. project_documentation-0.4.0/examples/e-foc/templates/requirements.md +6 -0
  10. {project_documentation-0.2.0 → project_documentation-0.4.0}/pyproject.toml +1 -1
  11. {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/__init__.py +1 -1
  12. {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/build_documentation_pdfs.py +16 -6
  13. {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/generate_requirements_pdf.py +28 -26
  14. project_documentation-0.4.0/tests/integration/__init__.py +1 -0
  15. project_documentation-0.4.0/tests/integration/test_cli_integration.py +357 -0
  16. project_documentation-0.4.0/tests/unit/test_build_documentation_pdfs.py +163 -0
  17. project_documentation-0.4.0/tests/unit/test_generate_requirements_pdf.py +132 -0
  18. project_documentation-0.2.0/CHANGELOG.md +0 -34
  19. {project_documentation-0.2.0 → project_documentation-0.4.0}/.gitignore +0 -0
  20. {project_documentation-0.2.0 → project_documentation-0.4.0}/LICENSE +0 -0
  21. {project_documentation-0.2.0 → project_documentation-0.4.0}/examples/e-foc/documentation/theory.md +0 -0
  22. {project_documentation-0.2.0 → project_documentation-0.4.0}/examples/e-foc/requirement.schema.json +0 -0
  23. {project_documentation-0.2.0 → project_documentation-0.4.0}/examples/e-foc/requirements/foc.yaml +0 -0
  24. {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/generate_traceability_matrix.py +0 -0
  25. {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/validate_documents.py +0 -0
  26. {project_documentation-0.2.0 → project_documentation-0.4.0}/src/project_documentation/validate_requirements.py +0 -0
  27. {project_documentation-0.2.0 → project_documentation-0.4.0}/tests/__init__.py +0 -0
  28. {project_documentation-0.2.0 → project_documentation-0.4.0}/tests/unit/__init__.py +0 -0
  29. {project_documentation-0.2.0 → project_documentation-0.4.0}/tests/unit/test_generate_traceability_matrix.py +0 -0
  30. {project_documentation-0.2.0 → project_documentation-0.4.0}/tests/unit/test_validate_documents.py +0 -0
  31. {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.4
1
+ Metadata-Version: 2.5
2
2
  Name: project-documentation
3
- Version: 0.2.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: "Python version to set up"
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 latest from PyPI.
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 project-documentation
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
- sudo apt-get update -qq
154
- sudo apt-get install -y --no-install-recommends \
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 = latest from PyPI. |
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
@@ -0,0 +1,6 @@
1
+ # Requirements Document
2
+
3
+ This document provides a structured overview of all project requirements.
4
+
5
+ ---
6
+
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "project-documentation"
7
- version = "0.2.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"
@@ -1,3 +1,3 @@
1
1
  """project-documentation — documentation pipeline for embedded projects."""
2
2
 
3
- __version__ = "0.2.0"
3
+ __version__ = "0.4.0"
@@ -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 convert_markdown_dirs(docs_dirs: list[str], version: str, output_dir: Path) -> None:
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 / f"e_foc-{category}-{name}-{version}.pdf"
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 / f"e_foc-requirements-{version}.pdf"
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 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"))
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
- if section not in sections:
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
- "pandoc", str(md_path),
53
- "-o", str(args.output),
54
- "--toc",
55
- "-V", "geometry:margin=1in"
56
- ], check=True)
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