(Lack of) consistency of docstring quotation marks

[arporter]

@schreiberx has pointed out that we're not consistent in whether we use ''' or """ for docstrings. In the wiki example markup we use ''' (but don't say that's required) and, in fparser, Black has converted everything to """. I would therefore vote that we madate the use of """, update the wiki appropriately, and update docstrings on a "you touch it, you fix it" basis. (Or we find a quiet slot over Christmas and do it as a big bang.)
What do @TeranIvy @hiker and @sergisiso think?

[schreiberx]

You didn't ask me, but I like how this is handled in fparser: Just run black over it and that's it.

[arporter]

Oh yes, that's a good point. Much though I'm not totally a fan of black, having one less thing to worry about when doing a code review is very valuable.

[hiker]

IMHO no way for 3.0. And still the case, I have two long-outstanding PRs that would potentially very heavy affected by any global change (due to refactoring code from lfric and gocean into a common base class), causing me a lot of overhead. Also while I am in favour of types, if we require full type checking compliance ny running e.g. myp, expect quite a bit of overhead, python typing sometimes behaves quite unexpected (not saying wrong ;) ), esp. when using optional variables.

[sergisiso]

We decided with @arporter that for type-annotations we won't do a big bang change for now, instead we will follow a gradual approach. We are allowed/encouraged to start using them for new code or code being changed, if they are supported by our oldest python in the tests (currently 3.7). It is ok to still use sphinx-types for cases that are not well supported with this older python versions.

We saw that Sphinx already handles them with linkable references in the autodocs by default, what does the shpinx-autodoc-typehints do @schreiberx ? Just provide more control on how these are formatted?

[schreiberx]

What do you mean by "what does the shpinx-autodoc-typehints"? It supports type hints in sphinx but that was probably not your question.
The advantage of type hints is that they can be used by modern code development tools to provide more information on the variable, do additional type-checking in the editor, etc.

[sergisiso]

Type-hints in sphinx already work out-of-the-box without this extension, that's why I am asking

[schreiberx]

Let's please discuss this f2f on Friday. I have the impression we're both assuming different things as to why we should use type hints directly in Python.