Fix doc issue where parameters listed twice in description

[lorenzncode]

Fix doc issue where parameters could be listed twice in the method description

• Remove sphinx extension sphinx_autodoc_typehints

• Update sphinx pin to version 4.2.0

• Show typehints in both signature and description

[lorenzncode]

To resolve #819.

[codecov]

Codecov Report

Merging #916 (1548bb4) into master (3efb080) will not change coverage.
The diff coverage is n/a.

❗ Current head 1548bb4 differs from pull request most recent head 9b13724. Consider uploading reports for the commit 9b13724 to get more accurate results

@@           Coverage Diff           @@
##           master     #916   +/-   ##
=======================================
  Coverage   96.29%   96.29%           
=======================================
  Files          40       40           
  Lines        9364     9364           
  Branches     1101     1101           
=======================================
  Hits         9017     9017           
  Misses        204      204           
  Partials      143      143           

📣 Codecov can now indicate which changes are the most critical in Pull Requests. Learn more

[jmwright]

I think this looks fine. Thanks @lorenzncode

[adam-urbanczyk]

Looks good @lorenzncode . One minor point - would it be easy to move self to the top?

[lorenzncode]

Yes, it's easy to move self to the top. I'll update the PR shortly.

[lorenzncode]

I see one open issue to debug - the methods with Literal in the signature are rendered with strikethrough:

I also clobbered the existing setup() function that adds tables.css.

[lorenzncode]

With docutils 0.16, the result is as expected:

Prior result with strikethrough text was using docutils 0.17.1. HTML is <s><span class="pre">'XY'</span></s>

Perhaps related to https://docutils.sourceforge.io/HISTORY.html

Use HTML text-level tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>, <i>, <b>, <u>, <mark>, and <bdi> if a unique, matching class value is found in inline and literal elements. Use <ins> and <del> if a unique matching class value is found in inline, literal, or container elements. Use <small> for generated code line numbers.

[lorenzncode]

The html (strikethrough) issue was reported by another user as sphinx-doc/sphinx#9872. I will update this PR after sphinx 4.3.1 is released.

[adam-urbanczyk]

Shall I merge or wait for 4.3.1 @lorenzncode ?

[lorenzncode]

I'd propose to wait for sphinx 4.3.1. I expect the release soon based on comments in the GH issues and the sphinx 4.3.1 release milestone tracker. I'll watch for the release then update this PR to pin to sphinx 4.3.1.

[lorenzncode]

Sphinx 4.3.1 is out! The docs look good to me now (other than the known docstring issues mentioned in #922 to be fixed separately).

[jmwright]

Looks like there's a glibc error with Python 3.9 in Azure's Linux runs.

[adam-urbanczyk]

Yup, will look into this

[lorenzncode]

• Update sphinx pin to version 4.4.0
• Test with new autodoc_typehints_format setting; compare 'fully-qualified' vs 'short'

I'd like to complete the tasks above before this is merged.

[lorenzncode]

This could be a good time for this PR as it will resolve the current Read the Docs build failures (for example see PR #1018).

[jmwright]

@lorenzncode Sounds good. It has two approvals, and all the conversation items have been addressed, so I think it is ready to merge. Do you want to do the honors?

[jmwright]

Thanks for fixing this @lorenzncode