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

Created on 12 Jul 2019 · 8Comments · Source: sphinx-doc/sphinx

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

autodoc bug

Source

pavel-kirienko

All 8 comments

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.

tk0miya on 13 Jul 2019

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.

pavel-kirienko on 13 Jul 2019

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.

tk0miya on 15 Jul 2019

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?

pavel-kirienko on 15 Jul 2019

👍1

Fixed by #6578.
Thank you for reporting.

tk0miya on 1 Aug 2019

❤1

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

tk0miya on 1 Aug 2019

Note: