Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Typehints derived from type comments not properly handled in generated signature and parameters #318

Closed
fmigneault opened this issue Jan 9, 2022 · 3 comments
Closed

Typehints derived from type comments not properly handled in generated signature and parameters #318

fmigneault opened this issue Jan 9, 2022 · 3 comments
Labels
Bug Language: Python

Comments

@fmigneault
Copy link

When type hints are generated for class methods that provide the types using the comment annotation format, some cases are not handled correctly. (i.e.: using # type: (<args>) -> <return>)

  1. Base classes are replaced by the first argument from their corresponding __init__ call.
    For some reason, the Parameters section for the class' __init__ are not reported anywhere.
    (maybe because they are already processed as base class components, instead of self, so no more parameters to process?)
  2. Parameters in other methods have their types offset by one.

All this is most definitely caused by inspect.signature that does not include self or cls definitions, since they are not to be provided type comments definitions (similar to how the instance reference is automatically passed during the method call and must not be passed as argument).
Instead of inspect.siganture, one should use inspect.getfullargspec to obtain the full arguments derived from type comments, including self for methods or cls for classmethods.

Use cases are demonstrated in below images.

using autodoc_typehints = "description"

image

with autodoc_typehints disabled

image

corresponding code:

image

source code for reference: https://github.com/Ouranosinc/Magpie
and config: https://github.com/Ouranosinc/Magpie/blob/master/docs/conf.py
@mathbou
Copy link
Contributor

mathbou commented Jan 20, 2022

I made a PR (#300) months ago about this problem, still waiting for review 😕

@fmigneault fmigneault mentioned this issue Jan 20, 2022
Merged
@AWhetter
Copy link
Collaborator

Apologies for taking so long to look at #300. That PR has now been merged so please let me know if this is still an issue.

netbsd-srcmastr pushed a commit to NetBSD/pkgsrc that referenced this issue May 6, 2023
@0-wiz-0
py-sphinx-autoapi: update to 2.1.0.
cadba75 
v2.1.0 (2023-03-28)
-------------------

Deprecations and Removals
^^^^^^^^^^^^^^^^^^^^^^^^^

- Support for documenting languages other than Python is deprecated. (#248)
- Removed the option to have autoapi generate toctree entries for domain objects.
  Domain objects are now added to the toctree by Sphinx.
  Dropped support for sphinx < 5.2.0. (#369)


Misc
^^^^

- Added basic type checking.
- Integrated towncrier into the release workflow.


v2.0.1 (2023-01-16)
-------------------

Features
^^^^^^^^
- Can turn off the addition of documented objects to the TOC tree.
- Added support for Python 3.11.

Bug Fixes
^^^^^^^^^
- `#330 <https://github.com/readthedocs/sphinx-autoapi/issues/330>`: (Python)
  Render tuple values as tuples, not lists.
- `#341 <https://github.com/readthedocs/sphinx-autoapi/issues/341>`: (Python)
  Fix module level assignments to class attributes being documented as
  module level attributes.
- (Python) Fix "bysource" sort order showing items in alphabetical order.
- (Python) Use the correct directives for a variable type and value.

Trivial/Internal Changes
^^^^^^^^^^^^^^^^^^^^^^^^
- Removed some autogenerated test data from the repository.


v2.0.0 (2022-09-27)
-------------------

Breaking Changes
^^^^^^^^^^^^^^^^

- Dropped support for Sphinx <4.
- `#352 <https://github.com/readthedocs/sphinx-autoapi/issues/352>`: (Python)
  Properties are rendered with the ``property`` directive,
  fixing support for Sphinx 5.2.
  A new ``PythonPythonMapper`` object (``PythonProperty``) has been created
  to support this change. This object can be passed to templates, filters,
  and hooks.
  A new ``property.rst`` template has also been created to support this change.

Trivial/Internal Changes
^^^^^^^^^^^^^^^^^^^^^^^^
- Use https links where possible in documentation.
- Pass correct argument types to ``status_iterator``.


V1.9.0 (2022-07-25)
-------------------

Breaking Changes
^^^^^^^^^^^^^^^^

- Dropped support for Python 3.6.

Features
^^^^^^^^

- Added support for Python 3.10.
- `#222 <https://github.com/readthedocs/sphinx-autoapi/issues/222>`:
  Marked extension as parallel read safe.

Bug Fixes
^^^^^^^^^
- `#324 <https://github.com/readthedocs/sphinx-autoapi/issues/324>`: (Python)
  Fail elegantly when no source files are found.
- (Python) Stop calling ``autodoc-process-docstring`` when docstring is empty.
  Works around sphinx-doc/sphinx#10701.
- `#318 <https://github.com/readthedocs/sphinx-autoapi/issues/318>`: (Python)
  Fixed misaligned argument types on methods/classmethods when using type comments.
- `#278 <https://github.com/readthedocs/sphinx-autoapi/issues/278>`: (Python)
  Limit signatures to 60 characters in summaries.
- Fix keyerror when using markdown sources.
- `#328 <https://github.com/readthedocs/sphinx-autoapi/issues/328>`: (Python)
  Fix kw-only marker getting ignored if first in the signature.

Trivial/Internal Changes
^^^^^^^^^^^^^^^^^^^^^^^^
- Fixed tests in Sphinx 5.
- Fixed many typos throughout the documentation.
@AWhetter
Copy link
Collaborator

Closing due to lack of feedback and assuming that the merged pull request fixed this issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Bug Language: Python
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@AWhetter @mathbou @fmigneault