I was putting together what I hope is a pretty simple PR to add the
MultiTrace documentation to the
API documentation (see below for related question). One thing confuses me, as a relative Python novice: what’s the right format for docstrings? The format I see in the code for
MultiTrace looks right to me, and it looks good when it is displayed in a console. But when I look at the documentation it produces in HTML, it doesn’t look good at all. For example, the formatting of parameters and their type information looks bad (the
: is dropped).
As I said, I’m a python novice, so what’s the right way to deal with this? I have tried looking at the ReStructured Text documentation, and IIUC, what they propose would look terrible when read in a console – it’s full of distracting markup.
Am I misunderstanding something here? Is there some happy medium that I don’t know about?
Also, a side question – it seems like the
MultiTrace docs could go either in the “inference” chapter or in the backends chapter. TBH, although by code it belongs in the latter, to understand inference, I believe it belongs in the former. Suggestions? Requests? Demands?