[ci,doc] CMDGEN error can be a bit confusing
Open
@HU90m is already working on this.
Since Jun 2, 2023.
Component:CI
Component:Doc
Earlgrey-PROD Triaged
- Dominant language
- SystemVerilog
- Stars
- 3.6k
- Forks
- 1.1k
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 141
Description
Description
From https://github.com/lowRISC/opentitan/pull/18782#issuecomment-1573705361
Full error output from CMDGEN tool, as seen in CI output.
Starting: Check CMDGEN Blocks
==============================================================================
Task : Bash
Description : Run a Bash script on macOS, Linux, or Windows
Version : 3.214.0
Author : Microsoft Corporation
Help : https://docs.microsoft.com/azure/devops/pipelines/tasks/utility/bash
==============================================================================
Generating script.
Script contents:
ci/scripts/check-cmdgen.sh
========================== Starting Command Output ===========================
/usr/bin/bash /home/vsts/work/_temp/99541db1-d037-4930-902c-8deab2f4f4dd.sh
INFO:__main__:util/tlgen/README.md:L56: `util/selfdoc.py tlgen` output the following error messages:
ERROR:root:['list of group', 'comma separated group of key:value enclosed in `{}` the second entry of the list is the sub group format']
ERROR:root:['list of group', 'comma separated group of key:value enclosed in `{}` the second entry of the list is the sub group format']
INFO:__main__:hw/ip/aes/doc/interfaces.md:L2: Generated content needs updating.
##[error]Documentation generated using CMDGEN blocks is not up to date.
Update blocks with: ./util/cmdgen.py -u '**/*.md'
##[error]Bash exited with code '1'.
Finishing: Check CMDGEN Blocks
I found the error output from CMDGEN check failing in CI to be a bit confusing. This mostly comes down to the tool checking all blocks in the codebase, then reporting stderr from other blocks as well as reporting which block caused the CI failure.
(...)
========================== Starting Command Output ===========================
INFO:__main__:util/tlgen/README.md:L56: `util/selfdoc.py tlgen` output the following error messages:
ERROR:root:['list of group', 'comma separated group of key:value enclosed in `{}` the second entry of the list is the sub group format']
ERROR:root:['list of group', 'comma separated group of key:value enclosed in `{}` the second entry of the list is the sub group format']
INFO:__main__:hw/ip/aes/doc/interfaces.md:L2: Generated content needs updating.
##[error]Documentation generated using CMDGEN blocks is not up to date.
Update blocks with: ./util/cmdgen.py -u '**/*.md'
(...)
In the excerpt above, the first three lines are unrelated to the failure in the bottom three lines. At a glance, this caused (me) confusion.
Suggestions:
- Re-arrange the output of the tool to make it easier to follow. For example :
========================== Starting Command Output ===========================
##[info] Running CMDGEN tool....
##[error] Documentation generated using CMDGEN blocks is not up to date.
Update all blocks with: ./util/cmdgen.py -u '**/*.md'
##[info] The following CMDGEN blocks caused the failure:
INFO:__main__:hw/ip/aes/doc/interfaces.md:L2: Generated content needs updating.
##[info] While executing, the following CMDGEN blocks produced the following stderr:
INFO:__main__:util/tlgen/README.md:L56: `util/selfdoc.py tlgen` output the following error messages:
ERROR:root:['list of group', 'comma separated group of key:value enclosed in `{}` the second entry of the list is the sub group format']
ERROR:root:['list of group', 'comma separated group of key:value enclosed in `{}` the second entry of the list is the sub group format']
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.