Attach docstrings to NewTypes at runtime

[Seth Fitzsimmons (mojodna)]

Summary

• Convert bare triple-quoted strings after NewType assignments into explicit __doc__ assignments so docstrings are accessible at runtime
• Python treats post-assignment docstrings as expression statements, never attaching them to the NewType object (__doc__ stays None)
• Same pattern DocumentedEnum uses for enum member docs

Affected packages

• overture-schema-system (primitives, strings, ref/id)
• overture-schema-core (names, opening_hours)

[Victor Schappert (vcschapp)]

Can we talk about this? It breaks the documentation generator (pdoc IIRC), which has a special hack mode that recognizes docstrings coming after variables, but it doesn't support reading __doc__ on those values.

[Seth Fitzsimmons (mojodna)]

Interesting... I had to do this to support Markdown/code generation because the docstrings that come after the NewType definitions weren't accessible programmatically (the opposite problem). It'd be interesting to see what proc's workaround is in case that's appropriate to incorporate in my work.

[Roel Bollens (RoelBollens-TomTom)]

I also ran into the same issue where rather than explicit __doc__ field assignment I used the Field(description="...") instead. This still doesn't help with the pdoc documentation generation but wanted to mention it as there are models which currently document their fields in this way.

An other related issue I've come across has been with the Segment alias which is also not know anymore at runtime which I had solved using Field(title="...").

[Jennings Anderson (jenningsanderson)]

👍 I think optimizing for markdown code generation here is okay for the moment, as this is what's required for our reference docs. We can/should revisit in the future for other documentation generators.