Docs: In param lists mark up multiple types correctly

[erlend-aasland]

Use the word 'or' instead of the symbol '|'.

See also the Sphinx docs:

• https://www.sphinx-doc.org/en/master/usage/domains/python.html#send_message

---

📚 Documentation preview 📚: https://cpython-previews--116389.org.readthedocs.build/

[AlexWaygood]

My first reaction was "but these aren't valid Python type hints anymore!"

My second reaction was to go... "Wait, he's right, these are probably much more readable for casual readers of the documentation who might not be familiar with Python's typing system" :)

[AlexWaygood]

Is this one still perhaps a bit too complex for the docs? Not sure how it could be simplified, though

[erlend-aasland]

It is definitely complex. In this case, I'd say readability is definitely improved using or iso. |.

[hugovk]

I checked the first one:

Before	After

Both are linked and marked up the same. Are there some instances where there's a difference (other than "|" vs. "or")?

Should we be formatting None as None? https://devguide.python.org/documentation/markup/#quick-reference

[erlend-aasland]

Both are linked and marked up the same. Are there some instances where there's a difference (other than "|" vs. "or")?

@hugovk: indeed, it looks like they are all the same. I also tried just using a comma (:type name: str, dict), which is also marked up like this. Looks like it just boils down to a style issue. Do we want it written as str or dict, or str | dict? See also @AlexWaygood's comment: #116389 (comment).

[hugovk]

No strong preference either way.

In theory, if Sphinx says to do it one way, it makes sense to do that. In practice, if it makes no difference, let's pick the one we prefer. So I'll leave it up to you ;)

[erlend-aasland]

In theory, if Sphinx says to do it one way, it makes sense to do that. In practice, if it makes no difference, let's pick the one we prefer. So I'll leave it up to you ;)

It's a minor style issue to decide on, nevertheless it feels wrong for me to decide on the convention in a PR. I think at least a heads-up in the Documentation category on Discourse would be nice :)

UPDATE: I created a topic on Discourse.

[erlend-aasland]

Marked as draft until a decision has been made.