sphinx-autoapi icon indicating copy to clipboard operation
sphinx-autoapi copied to clipboard

Module table of contents are poorly formatted when long type hints are present

Open zaneselvans opened this issue 2 years ago • 2 comments

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.

See this module for example.

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.

zaneselvans avatar Sep 28 '21 15:09 zaneselvans

A simple fix is to add the :nosignatures: option to the ..autoapisummary:: directive in the Functions section here.

phausamann avatar Oct 06 '21 08:10 phausamann

: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.

EHYPI avatar Dec 01 '21 15:12 EHYPI