Autodoc issues: bad ordering, missing hyperlinks, missing type information

[pavel-kirienko]

There appear to be several issues with Autodoc.

Steps to reproduce the behavior:

$ git clone https://github.com/pavel-kirienko/sphinx-issues-mwe
$ cd sphinx-issues-mwe
$ pip install -r requirements.txt
$ cd docs
$ make html

I have set up an MWE on RTD which you can browse here: https://sphinx-issues-mwe.readthedocs.io; the sources are at https://github.com/pavel-kirienko/sphinx-issues-mwe.

• The entities should follow the same order as in the source. The setting bysource is ignored by Autodoc.
• The base classes are listed but not hyperlinked.
• Property type information is discarded.
• Method argument type information is discarded.

Environment info

• OS: GNU/Linux
• Python version: 3.7
• Sphinx version: 2.1
• Sphinx extensions: sphinx.ext.autodoc
• Extra tools: N/A

[tk0miya]

Thank you for reporting.

The entities should follow the same order as in the source. The setting bysource is ignored by Autodoc.

At present, autodoc_member_order = 'bysource' only refers definition order of classes, methods and variables on the target module. It does not refers order of imports. I don't think this is a bug. But it would be better if supported.

The base classes are listed but not hyperlinked.

It will be hyperlinked if you make a document for sphinx_demo._internal.Entity. I guess you'd like to link it to sphinx_demo.Entity. But it is hard to determine sphinx_demo._internal.Entity equals sphinx_demo.Entity.

Property type information is discarded.

So far, type annotations for variables and properties are not supported. +1 for supporting.

Method argument type information is discarded.

I just posted #6576 to fix this bug.

[pavel-kirienko]

I don't think this is a bug. But it would be better if supported.

Indeed, that would be great. For now at least the documentation should be updated because the way it's described now makes one expect that it applies to all types of entities across the codebase.

It will be hyperlinked if you make a document for sphinx_demo._internal.Entity. I guess you'd like to link it to sphinx_demo.Entity. But it is hard to determine sphinx_demo._internal.Entity equals sphinx_demo.Entity.

You understood my intent correctly, yes. My codebase is organized as a collection of deeply nested submodules containing implementation details. Entities that form the API are exposed to the user through explicit re-exports in __init__.py. I see now that this pattern is not supported by Autodoc, which is unfortunate. If you're interested you can find the codebase here https://github.com/UAVCAN/pyuavcan/tree/5d27af38d65ff15c0c1245ebae39ef4c209550da/pyuavcan.

As a stop-gap measure, I ended up making a small custom extension that subscribes to missing-reference and fixes all module names containing ._ (as in module._private.Entity --> module.Entity). I can't imagine myself to be the only user needing this, since it is a commonly used pattern, especially for larger codebases. Would it be possible and sensible to implement such auto-replacement as an option for Autodoc? I realize that this solution is really suboptimal but I'm building it on the premise that it is hard for the generator to establish equivalence between module._private.Entity and module.Entity, as you said.

[tk0miya]

Indeed, that would be great. For now at least the documentation should be updated because the way it's described now makes one expect that it applies to all types of entities across the codebase.

#6578 will resolve this. I'll merge it soon. Please try it.

Would it be possible and sensible to implement such auto-replacement as an option for Autodoc? I realize that this solution is really suboptimal but I'm building it on the premise that it is hard for the generator to establish equivalence between module._private.Entity and module.Entity, as you said.

There might be many kind of import patterns. So such heuristic process is not good for core.

[pavel-kirienko]

#6578 will resolve this. I'll merge it soon. Please try it.

This is just great, thank you! The linked branch seems to work just the way it should. Is the fix going to be available in the next release?

There might be many kind of import patterns. So such heuristic process is not good for core.

I understand, but please observe that a replacement that removes underscored submodules (like _foo) will always yield a valid name in the end if two conditions are met:

• The name is actually exported in the first non-underscored package. For example, foo.bar._baz.Zoo --> foo.bar.Zoo is a valid replacement if bar reexports Zoo.
• Modules never reexport hidden items from anywhere except their own direct submodules. This is (implicitly) required by PEP8.

Many similarly organized packages could benefit from Autodoc supporting this heuristic through an option (disabled by default). Are you totally opposed to this, or would it be possible for me to, perhaps, build a stronger case in favor of this optional feature?

[tk0miya]

Fixed by #6578.
Thank you for reporting.

[tk0miya]

Ah, sorry. #6578 is part of this issue. Reopened.

[tk0miya]

Note:

The entities should follow the same order as in the source. The setting bysource is ignored by Autodoc.

Fixed by #6578.

The base classes are listed but not hyperlinked.

Will be discussed at #7493.
I think #7463 will help to resolve this issue. But we need to discuss compatibility with other maintainers.

Property type information is discarded.

Will be discussed at #7383.
I hope this will be fixed in 3.1.

Method argument type information is discarded.

Fixed by #6576.

[tk0miya]

I think there are similar issues now. So I'm closing this now. Please follow #7383 and #7493. Thanks,