readthedocs / readthedocs/sphinx-autoapi

Types from attrs.define classes not shown in description

Open
#551 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
494
Forks
147
Avg merge
9m
Merged PRs (30d)
1

Description

Say I have an attrs class, e.g.:

import attrs

@attrs.define
class MyClass:
    """
    A class that does something.

    Parameters
    ---------
    a
        The parameter a
    """

    a: float = attrs.field()

Then in my conf.py I have added "sphinx.ext.autodoc" to the extensions list, and set autodoc_typehints = 'description'. I expect that in the generated API docs that the parameter "a" should get the type "float" added to its description, but I don't.

My actual repo (pointing to a PR where Ive added autoapi): https://github.com/21cmfast/21cmFAST/pull/575
A specific class showing this behaviour: https://github.com/21cmfast/21cmFAST/blob/b0eaa28630f8da31e889fa1badad6892732a4718/src/py21cmfast/wrapper/inputs.py#L1448
The generated docs for this class: https://21cmfast--575.org.readthedocs.build/en/575/

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the attrs.define example and the conf.py setting autodoc_typehints = 'description', then compare the generated documentation for the linked inputs.py class. Trace how sphinx.ext.autodoc handles the parameter description and verify that the generated API docs include the float type for parameter a.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.