Add a script to allow inlined test documentation
Get series with b4
b4 am [email protected]Versions newest first · linked by author and title
- v3 Latest1 patch 1 replyIn review
- v21 patch 2 repliesSuperseded
- v11 patch 0 repliesSuperseded
Changes in v3 from the cover letter
- Added MIT license;
- Some cleanups on its comments;
- Use enumerate() and remove fileinput import;
- Print an error if the field is invalid;
- Kept just one form (either singular or plural) to fields;
- Added a more comprehensive python documentation for the class, explaining how wildcards are processed;
- Some cosmetic changes;
- Fixed some typos at fields array.
Patches in v3 No applies recorded yet
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/1 | scripts:igt-doc.py: add a parser to document tests inlinedscripts/ | +575 | 0 replies |
Reviews trailers per patch
No Reviewed-by, Acked-by or Tested-by trailers for v3 yet.
Cover letter [igt-dev] [PATCH i-g-t v3 0/1] Add a script to allow inlined test documentation
From: Mauro Carvalho Chehab <[email protected]>
Keeping documentation updated is hard, as text documents gets outdated when code changes. The best practices are to keep documentation as close as possible to the code.
This script allows adding documentation inside special tags at the C files, and validate if the documentation actually meets the code.
It is meant to be used by the new Intel Xe driver, in the process of being upstreamed. It can be used also for other drivers, as well.
It supports three modes of operation:
1) Output documentation in ReST format (default if no arg provided):
$ scripts/igt-doc.py --files tests/xe/*.c --rest
2) Output a list of tests that are documented
$ scripts/igt-doc.py --files tests/xe/*.c --show-subtests
3) Compare the documented testlists with IGT runner testlist:
$ scripts/igt-doc.py --files tests/xe/*.c --check-testlist
The idea is to add automation to generate the ReST files at the Xe meson.build file. Once all documentation for Xe is placed inline, the CI for it can also use this script to discover documentation gaps.
Both modes (1) and (2) can be tested by running:
$ ./scripts/igt_doc.py --files ./scripts/igt_doc.py
This will use the strings inside the class docstring added on version 3, parsing them as if they're C file documentatoin.
---
v3:
- Added MIT license;
- Some cleanups on its comments;
- Use enumerate() and remove fileinput import;
- Print an error if the field is invalid;
- Kept just one form (either singular or plural) to fields;
- Added a more comprehensive python documentation for the class, explaining how wildcards are processed;
- Some cosmetic changes;
- Fixed some typos at fields array.
v2:
- Convert to Python
Mauro Carvalho Chehab (1):
scripts:igt-doc.py: add a parser to document tests inlined
scripts/igt_doc.py | 575 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 575 insertions(+) create mode 100755 scripts/igt_doc.py
Signature · 1 line
2.39.0