Hdl21 isn't especially "API heavy"; unlike, say, numpy, it doesn't have 5000 public functions with 15 arguments each. Accordingly we've never used automatic doc-generation. The docs instead have a more narrative tone, focusing on how to think about the various types, and use them in typical ways and contexts.
Nonetheless there have become swathes of Hdl21 that this would particularly benefit from such auto-docs, including:
The Primitive library, both the elements and their parameters
All the SimAttrs, their fields, etc
Similar lists of modifiers for Signal, Param, etc
Package-level functions, e.g. netlist, to_proto
Priorities for a good generator:
Write as little as possible (above & beyond the existing source code).
Certainly do not write that god forgiven ReST.
Use all our bazillion type-hints, at least to the extent possible(?)
No external site, hosting, or dedicated HTML.
Just produce Markdown; GitHub et al can host and render it great.
Actually... work on Hdl21?
We do lots of behind-the-scenes magic which will not necessarily be easily comprehended in every case.
Hdl21 isn't especially "API heavy"; unlike, say, numpy, it doesn't have 5000 public functions with 15 arguments each. Accordingly we've never used automatic doc-generation. The docs instead have a more narrative tone, focusing on how to think about the various types, and use them in typical ways and contexts.
Nonetheless there have become swathes of Hdl21 that this would particularly benefit from such auto-docs, including:
Primitivelibrary, both the elements and their parametersSimAttrs, their fields, etcSignal,Param, etcnetlist,to_protoPriorities for a good generator: