Links in function signatures not being resolved

[dstansby]

In the v3 docs, there are some internal references that aren't being linked in function signatures. For example, in the listing for zarr.Array, there should be a link for zarr.storage.StoreLike but there isn't. This is despite there being an entry for zarr.storage.StoreLike.

[dstansby]

StoreLike is showing up fine in the inventory, so I think the issue must be sphinx(-autoapi??) not inserting a cross link properly.

% python -m sphinx.ext.intersphinx _build/html/objects.inv | grep "StoreLike"
    zarr.storage.StoreLike                                                           : _autoapi/zarr/storage/index.html#zarr.storage.StoreLike
    zarr.storage.common.StoreLike                                                    : _autoapi/zarr/storage/common/index.html#zarr.storage.common.StoreLike

[dstansby]

In docs/_autoapi/zarr/storage/index.rst StoreLike is being documented as

.. py:data:: StoreLike

[dstansby]

I think we're running into https://github.com/sphinx-doc/sphinx/issues/10785 here

[jhamman]

@dstansby - you are probably the expert here. Do we see a path to fixing this?

[dstansby]

Not without https://github.com/sphinx-doc/sphinx/issues/10785 being fixed, which doesn't seem like it's going to happen soon. So definitely don't block v3 on this!

[d-v-b]

IMO the lack of this feature is a massive reason to move to some kind of documentation solution that works for type-annotated python projects. Since the linked sphinx issue is very stalled, I am wondering if we can get this functionality from mkdocs-material, which gives extra urgency to #3118

[d-v-b]

to be more specific: the autodoc plugin is the piece of the toolchain that's missing support for types. sphinx itself supports them.

[dstansby]

Would using mkdocs fix this? I seem to remember that I couldn't get this to work with mkdocs over at https://ome-zarr-models-py.readthedocs.io.

[d-v-b]

I think so. they have this working over in the mkdocs-based pydantic docs -- see https://docs.pydantic.dev/latest/api/base_model/#pydantic_core.SchemaValidator.title

[d-v-b]

[d-v-b]

in that example, str and FieldInfo are both links

[d-v-b]

i really don't want to rant out our docs... but if we just copied the pydantic docs (maybe not the color scheme) we would be massively improving things. I don't use our docs because I find them hard to naviagate. It's faster for me to read the source code than to use our docs. That's a big problem!

[dstansby]

str and FieldInfo are both class names, they are not type aliases. CoreSchema, which is a type alias in Pydantic is not linked in the attributes table below, which would suggest this isn't fixed even in mkdocs.

[d-v-b]

str is a type, not a class. See https://docs.pydantic.dev/latest/api/json_schema/#pydantic.json_schema.JsonSchemaMode for a type with a documentation entry (although we don't know if this was auto-generated or not)

[dstansby]

Nice - it looks like it is autogenerated: https://github.com/pydantic/pydantic/blob/702aaa6354cc30ae815676c57a8bbb4557ccb295/docs/api/json_schema.md?plain=1#L1

So mkdocs could hopefully solve this 🎉