How zephyrproject-rtos/reqmgmt works
Project Type and Purpose
• This repository is mainly a requirements management/documentation project built around the Zephyr Project requirements.
• Its purpose is to allow users (developers, project managers, etc.) to browse, edit, and generate documentation for project requirements using the StrictDoc tool.
File Structure
• The top-level directories include:
• .github: Contains CI configurations (e.g., GitHub workflows – “ci.yml”). This shows the existence of automated testing or documentation generation pipelines.
• docs: Contains two main subdirectories: software_requirements and system_requirements. These include “.sdoc” and “.sgra” files which capture requirements in StrictDoc’s supported formats.
• tools: Includes a Python script (import_zephyr_from_excel.py) that likely assists in importing requirements (e.g., from Excel) into the repository’s format.
• README.md: The main documentation guiding users on how to install StrictDoc, generate HTML exports, start a web server, and manage UIDs in the documentation.
• requirements.txt & tasks.py: Indicate a Python-based utility backbone to support the requirements management process.
• This file structure emphasizes a separation of documentation (in the docs folder) and automation/integration scripts (in tasks.py and the tools directory).
README for Additional Insights
• The README clarifies that the requirements are captured using StrictDoc.
• It provides instructions for generating static HTML documentation, running a web server for editing, and managing unique identifiers.
• It also provides the URL for the deployed documentation, suggesting that one of the main output artifacts is the HTML view of requirements.
• The mention in “System requirements” implies cross-platform compatibility and Python 3.7+ dependency.
a. Main Components:
• Requirements Repository:
• Documentation Storage: Represented by the “docs/software_requirements” and “docs/system_requirements” directories.
• Source Files: The “.sdoc” and “.sgra” files that encode the requirements in a structured format.
• StrictDoc Integration:
• Command-Line Interface (CLI): Used to export, browse, and manage requirements (i.e., “strictdoc export”, “strictdoc server”, and “strictdoc manage auto-uid”).
• StrictDoc Engine: The underlying engine doing the heavy lifting for processing the requirement documentation.
• Automation and CI Infrastructure:
• GitHub Workflows: Automated builds/validations as configured in the .github/workflows/ci.yml file.
• Tasks Scripts: The tasks.py file that might trigger or schedule automation jobs.
• Import/Conversion Utilities:
• Tools Module: Specifically, the import_zephyr_from_excel.py script that likely automates the process of importing requirements from Excel formats into the StrictDoc format.
b. Relationships and Interactions:
• Developers and automated systems trigger StrictDoc commands via the command line or CI.
• The StrictDoc engine processes the requirements source files to generate HTML documentation.
• The GitHub CI picks up changes (via the ci.yml workflow) and may automatically run validations or generate fresh HTML outputs.
• The tools module provides an integration point between external data (like Excel inputs) and the documentation repository.
c. Architectural Patterns and Principles:
• Separation of concerns: The documentation storage (docs) is clearly separated from automation scripts (tasks.py and tools) and the CI configuration (.github).
• File-based configuration: All requirements and system descriptions are maintained in plain files (using StrictDoc’s formats).
• Modularity: Each component (import tools, StrictDoc engine, CI pipeline) plays a distinct role in the overall documentation lifecycle.
d. Relevant Technologies and Frameworks:
• Python (with a minimum version of 3.7).
• StrictDoc (for managing requirement documents).
• GitHub Actions (for continuous integration workflows).
• Possibly additional libraries pulled in via requirements.txt, which support the overall automation.