add option to put docstrings on model attributes

[eli-bl]

Adds a docstrings_on_attributes option that causes property descriptions to appear in docstrings on the attributes, instead of in the class docstring. This is a desirable behavior when using documentation generators like Sphinx.

This is a non-breaking change; if the option is not set, code generation is exactly the same as before (evidence: the existing golden-record directories have no changes).

Clarification about how docstrings on attributes work

Python does not treat all docstrings the same, in terms of availability at runtime. A docstring on a class or method is available as a __doc__ attribute— but a docstring on an attribute is not; such a string is just thrown away by the interpreter. If class A has attribute b, then A.b.__doc__ will never be a thing— you would have to define b as a property getter method instead.

However, docstrings on attributes are still valid as per PEP 257 as a thing that can be surfaced by other tools. Sphinx will use them when generating documentation, and VS Code will show them as a description in the popup if you hover over an attribute.

[dbanty]

Could you use a smaller OpenAPI document for the snapshots on this one so there will be fewer changes in the future as we tweak things?

Probably just a single endpoint & model would be enough to demonstrate it

[eli-bl]

@dbanty FYI, this was motivated partly by trying to build some HTML docs from a generated client with Sphinx, and finding that Sphinx really does not like how the current class docstrings are formatted. The format only really works if you view the strings as plain text; if it's interpreted either as Sphinx's default .rst format, or as Markdown, it becomes very garbled. That's the case even if the class & property descriptions are just plain text with no special markup - it's just a consequence of how indents & line breaks are being used in the template. Regardless of what kind of markup is supported by any particular tool, they are all likely to have opinions about those things, so it's kind of asking for trouble to try to create structured text like this out of multiple pieces of data. By contrast, the Python code structure, and the idea of class docstrings vs. attribute docstrings, is already something doc generators and IDEs understand.

[eli-bl]

@dbanty Btw, I updated the PR description to clarify the behavior of attribute docstrings in Python.