sphinx-autoapi
sphinx-autoapi copied to clipboard
Module table of contents are poorly formatted when long type hints are present
When a function has a very long call signature, potentially because it's making extensive use of type hints, the module table of contents generated by AutoAPI ends up being poorly formatted. The column with the function call signature in it becomes very wide, and the one-line docstring description gets squeezed off to the righthand side, potentially requiring scrolling to view.
Possible solutions might be stripping type hints from the call signature in the table of contents, or using a multi-line format for the call signature including type hints.
A simple fix is to add the :nosignatures:
option to the ..autoapisummary::
directive in the Functions section here.
:nosignatures:
This does not fix the issue for me (I edited the template file locally). I am also using the option autodoc_typehints = "description"
I'm also getting a docutils error:
Exception occurred:
File "/home/[UserName]/[Environment_Folder]/lib/python3.8/site-packages/docutils/writers/_html_base.py", line 1559, in visit_title
assert isinstance(node.parent, nodes.section)
AssertionError
I commented out the assertion line in the docutils package (version 0.17.1) because I never found any guidance as to the cause. This may be related to the poor formatting (no other formatting issues are present though). Adding the no-signatures option does not prevent the AssertionError, nor fix the poorly formatted table.