API Doc Generation

[dan-fritchman]

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:

1. 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(?)

2. No external site, hosting, or dedicated HTML.

• Just produce Markdown; GitHub et al can host and render it great.

3. Actually... work on Hdl21?

• We do lots of behind-the-scenes magic which will not necessarily be easily comprehended in every case.
• This will in some cases conflict with goal (1).