import module alias breaks reference doc

[dizcology]

Example: https://github.com/googleapis/python-documentai/blob/44ac766870080b84bdb23b7477624cf7570c5a33/google/cloud/documentai_v1beta2/types/document.py#L23

where we have:

from google.type import color_pb2 as gt_color

The same alias is then used in docstrings such as https://github.com/googleapis/python-documentai/blob/44ac766870080b84bdb23b7477624cf7570c5a33/google/cloud/documentai_v1beta2/types/document.py#L142

in this particular case sphinx seems to fail to capture that as a link, but even if it gets parsed as a cross reference link it results in a broken link since there would not be a doc for gt_color when the correct target is google.type.color. the same issue happens with ga_operation or types within the API itself.

[busunkim96]

For color_pb2 there's no published documentation for google.type.color_pb2 (one of the common protos) so I wouldn't expect a nice link.

I opened https://github.com/googleapis/python-api-common-protos/issues/2 to explore publishing documentation for the common protos.

That said, none of the references to library types are getting turned into nice links, so something seems to be off.

• https://github.com/googleapis/python-documentai/blob/44ac766870080b84bdb23b7477624cf7570c5a33/google/cloud/documentai_v1beta2/types/document.py#L139
• https://googleapis.dev/python/documentai/latest/documentai_v1beta2/types.html#google.cloud.documentai_v1beta2.types.Document.Style

I'll poke around a bit more to see what's happening.

[busunkim96]

It seems like an absolute reference works best for sphinx.

for example: ~google.cloud.documentai_v1beta2.types.BatchProcessDocumentsRequest

Changes will need to be made to https://github.com/googleapis/gapic-generator-python/blob/68d68aecd80987a06c3100be2d335498a996b427/gapic/schema/metadata.py#L157-L163

[hkdevandla]

@busunkim96 , thanks for chiming in. Can you assign the labels i.e assignee and priority to this issue.

Also wondering, what are the next steps here in terms of fixing the links?

CC'ed @software-dov

[busunkim96]

Triaged. I believe we'd have to tweak the schema and/or templates to get the generated libraries to always use absolute references.

[arithmetic1728]

any updates as we are out of slo

[busunkim96]

No updates. I am not actively working on this and have un-assigned myself to reflect reality.

I downgraded this to p3 since the documentation is still navigable.