Fix styling of punctuation in signatures

[jbms]

Fixes #76.

[jbms]

I think this is the simplest fix --- we just need to make sure it doesn't inadvertently break something else.

[2bndy5]

It looks to me like #76 was already fixed in #75 , but I'm in favor of this change since it is less generic and doesn't regress the current solution (as far as I can tell).

[2bndy5]

I don't think that adding mypy to intersphinx config settings will allow hyperlinking abstracted types (like Tuple, Dict, etc). It looks like the mypy docs don't actually declare the abstract types using the py domain, so we can't hyperlink the type hints. Currently, the python docs (already in our intersphinx config) do provide the abstractions found in collections.abc module.

[mhostetter]

I can confirm this PR fixes #76 for me. I see no side effects in my docs. Thanks!

Also, the object_description_options config is pretty neat! 🎉

[jbms]

The issue with hyperlinking Tuple, Dict and other types defined by the typing module is simply that they are defined in the typing module. In the TensorStore docs I have monkey patched the Python domain xref resolution to handle these as a special case.

[mhostetter]

@2bndy5 I think that's a bug in Sphinx. Notice, Union links correctly here, but Optional does not here.

I noticed something similar in my docs and added the autodoc-process-signature callback to resolve it. (I copied things I saw @jbms do in tensorstore)

def autodoc_process_signature(app, what, name, obj, options, signature, return_annotation):
    signature = modify_type_hints(signature)
    return_annotation = modify_type_hints(return_annotation)

    return signature, return_annotation

def modify_type_hints(signature):
    if signature:
        # Ensure types from the typing module are properly hyperlinked
        for type_name in ["Tuple", "List", "Sequence", "Dict", "Optional", "Union", "Iterator", "Type", "Literal"]:
            signature = signature.replace(f"{type_name}[", f"~typing.{type_name}[")
            signature = signature.replace("~typing.~typing", "~typing")

    return signature

def setup(app):
    app.connect("autodoc-process-signature", autodoc_process_signature)

[mhostetter]

Jinx... lol

[mhostetter]

I found that in functions and methods, typing.List was provided in the signature. However in properties, only List was provided, which didn't cross reference. A modified version of the above code was meant to add the typing. prefix to instances of List (etc) in signatures that didn't have it. 🤷