[tool, doc] Clarify autogenerated doc via "gen_cfg_md.py"
Nobody has claimed this yet.
- Dominant language
- SystemVerilog
- Stars
- 3.6k
- Forks
- 1.1k
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 141
Description
The autogenerated file `/doc/interfaces.md` requires some changes to be clearer:
1. `rst_n` port is defined (nor `rst_shadowed_n` when required). Even if the link to the "comportability" doc is provided, I think it should be there to be homogeneous as `clk` is defined.
2. When `rst_shadowed_n` is declared, a link to explain this feature should also be provided.
3. The widths should refer to the actual bus widths as the RTL does, rather than to the _array size_ of the port.
4. The column _Act_ is supposed to give the direction of the port, but `rcv`, `req`, and `rsp` are not clear. We should probably move to a less fancy way: column name _Direction_ and possible values `input`, `output` or `inout`.
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.
Research direction
Start by reading gen_cfg_md.py and tracing how it generates /doc/interfaces.md. Check the generated interface documentation against the RTL port widths and reset declarations, then verify that reset links and a clear Direction column with input, output, or inout values appear in the output.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, tooling
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100