lowRISC / lowRISC/opentitan

[ci,doc] CMDGEN error can be a bit confusing

Open
#18,798 2 comments 1 reaction 1 assignee View on GitHub

@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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.