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.

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

Use attribute docstrings for options #1762

Open
jyu00 opened this issue Jun 19, 2024 · 0 comments · May be fixed by #1897
Open

Use attribute docstrings for options #1762

jyu00 opened this issue Jun 19, 2024 · 0 comments · May be fixed by #1897
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@jyu00
Copy link
Collaborator

jyu00 commented Jun 19, 2024

What is the expected feature or enhancement?

Today most of the options dataclasses use the same Google style argument docstring as the rest of the modules. Unfortunately, the rendered API reference would list each field under both Parameters and Attributes, for example:

image image



The one exception is SamplerExecutionOptions, which only has attribute docstring. The generated doc therefore only shows the fields under Attributes:

image



I think this is a much nicer format, as you get both the description and type in one place.

@Eric-Arellano please let us know if you have better ideas!

Acceptance criteria

  • Use attribute docstring instead of argument docstring for options classes.

Also note that when I played with SamplerExecutionOptions, the text Default: True was not formatted correctly, so I don't know if there is special convention on specifying defaults.

@jyu00 jyu00 added the enhancement New feature or request label Jun 19, 2024
@kt474 kt474 added the documentation Improvements or additions to documentation label Aug 20, 2024
@kt474 kt474 self-assigned this Aug 29, 2024
@kt474 kt474 linked a pull request Aug 29, 2024 that will close this issue
@kt474 kt474 modified the milestone: 0.29.0 Aug 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants