Doc-as-Code
|
status: evaluated
|
||||
Doc-as-Code Verification Report#
Introduction#
Scope and purpose#
Generate documentation (.html files) based on text files (.rst / .md) and configuration data.
Inputs and outputs#
Inputs are restructured text files (.rst) and markdown files (,md) Outputs are HTML files (.html)
Fig. 15 Doc-as-Code overview#
Available information#
Project Documentation is available here:
Doc-as-Code Project Documentation
This includes getting started or usage information and integration manual.
The capabilities of the tool can be found here:
Installation and integration#
Tool location:
How to integrate:
Environment: github, python, Version 3.y.z, sphinx, Version x.y.z, sphinx-needs, Version x.y.z Supported platforms: Windows, Linux
Evaluation#
Use case Identification |
Use case Description |
Malfunctions |
Impact on safety? |
Impact safety measures available? |
Impact safety detection sufficient? |
Threats |
Impact on security? |
Impact security measures available? |
Impact security detection sufficient? |
Further additional safety measure required? |
Confidence (automatic calculation) |
|---|---|---|---|---|---|---|---|---|---|---|---|
1 |
Generate element (requirements, architecture, safety analysis, …) |
Wrong or missed element may lead to an wrong implementation with any potential error |
yes |
Reviews |
no |
Gain access to modify or run manipulated Doc-as-code or to to modify input files |
yes |
Access control, roles in Github |
yes |
Compare generated text in documentation with original text (#PR) |
low |
2 |
Link elements |
Wrong or missed links may lead to wrong elements and finally to wrong implementation with any potential error |
yes |
Reviews, Link rules checker |
no |
Gain access to modify or run manipulated Doc-as-code or to to modify input files |
yes |
Access control, roles in Github |
yes |
Compare generated links in documentation with original links (#PR) |
low |
3 |
Generate statistics |
Wrong or missing statistics may lead to wrong compliance statements, KPI reports, decisions |
yes |
Spot checks |
no |
Gain access to modify or run manipulated Doc-as-code or to to modify input files |
yes |
Access control, roles in Github |
yes |
Add diverse statistic generator tool (#PR) |
low |
4 |
Check documentation rules based on configuration |
Checks are not properly implemented, so may lead to wrong elements/links |
yes |
Code reviews, test for rules |
yes |
Gain access to modify or run manipulated Doc-as-code or to to modify input files |
yes |
Access control, roles in Github |
yes |
n/a |
high |
Result#
Tool Qualification Required
Tool Qualification#
Based on method: validation of the software tool
Requirements and testing aspects#
Tool requirements are defined here:
Test cases and tests are defined here:
Doc-as-Code Test cases and tests
The tests are part of the rules checker code sections.
Requirements coverage is documented here: