Right aligning internal references is very undesirable in API documentation with typed arguments

[achamayou]

This change was added here: bb46d32

Internal references are quite common in API documentation where arguments are typed, for example in this case, the return type is moved all the way right and overlaps with the source link:

This is even more disruptive when types are moved out of the argument list, like in this case with fr of type ForwardingRequired:

I don't know if there is easy way to make this change for [source] only without affecting all other internal references, but it seemed worth reporting this problem anyway. The theme looks fantastic other than that :)

[pradyunsg]

Could you share the documentation that this is happening with?

Either hosted online, or with a self-contained reproducer for it.

[achamayou]

Sure, you can checkout https://github.com/achamayou/CCF/tree/furo_theme and run "./livehtml.sh" on an Ubuntu 18.04 machine or similar. Then go to "Build Apps" and "Developer API" for example, or any of the pages whose title include "API", or even search for the names of the calls referenced in the screenshots.

If you have trouble getting this to work, I can also spin up a hosted version temporarily.

[pradyunsg]

Hiya! That took me a while -- could you spin up a hosted version?

[sirosen]

I've run into the same thing:

Reproducible with tox -e docs on this repo: https://github.com/globus/globus-sdk-python/

Just fussing in the style editor, I found that I could fix this by taking float: right off of the return type annotations.

example with float:right removed

Given how much nicer this looks with a multiline function signature, is it out of bounds to suggest that furo might format the text somewhat like black does long argument lists?
e.g.

foo(
   param1: str, param2: int, param3
) -> bool                                          [source]

[sirosen]

Ah, that is unfortunate!

I'm just starting to pick apart the autodoc HTML to try to see how src/furo/assets/styles/content/_api.sass could be tweaked, so I'm not really clear on the limitations. It seems like both the return type and [source] are marked as class="reference internal" when the return type of a function is an object.

I found that the issue can be reproduced by using automodule on a module with the following content:

class Bar:
     """bar object"""

def foo() -> Bar:
    """make a Bar"""
    return Bar()

If you remove the docstring from Bar (so automodule skips it), the content is properly aligned because the return type isn't a reference. But if you have a docstring on Bar, automodule will doc Bar and sphinx will make that return type annotation a reference, which gets matched by the a.reference.internal rule.

[sirosen]

I tried out a fix for this in #159 , which seems to work for me.

I wasn't sure, since this issue primarily occurs with autodoc, how to get similar content added to docs/kitchen-sink/. Right now, that seems like the best way to ensure that such a change is well-tested.
Would it be alright to add an internal-only subpackage, like furo._demo, which gets autodoc'ed in docs/kitchen-sink/autodoc.rst?

[achamayou]

I don't think it's necessary to use autodoc, for example the following is enough to reproduce the problem:

.. py:class:: Foo

.. py:function:: bar(foo: Foo) -> Foo

[sirosen]

Ah, good point! I rarely use the py:... directives and so didn't even think of them as a way of testing this.

I've never used viewcode without autodoc though, so I'm not sure how to get the [source] links included. I think it might be necessary to declare the class with a module name and then make that module available to sphinx. e.g.

.. class:: foo.Foo

with sphinx setup such that import foo will work. (Either installed or via path hacking in conf.py).

I'll try fiddling with it a little.

[achamayou]

Sorry, you are right, I hadn't thought of [source], and I can't find a way to make it work without autodoc either.

[pradyunsg]

This is now fixed, and a part of beta 35. Thanks @sirosen for the fix! ^>^