Type aliases and descriptions for parameters
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1
- Forks
- 3
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 17
Description
Problem: When using NewType or the Python 3.12 type alias, docstrings don't work. Sphinx extract the description from the comment after the alias definition, but for generating parameters for widgets we would like to use __doc__. Currently we have, e.g.,
BackgroundRun = NewType('BackgroundRun', int)
"""Background run: the run with only the solvent which the sample is placed in."""
I now tried the following:
def alias(name: str, tp: type, doc: str) -> type:
ntp = NewType(name, tp)
ntp.__doc__ = doc
return ntp
BackgroundRun = alias(
'BackgroundRun',
int,
"Background run: the run with only the solvent which the sample is placed in.",
)
Unless some Sphinx cache tricked be, this seems to work with both Sphinx autodoc and defined a usable __doc__.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Locate the code that creates widget parameter descriptions and the NewType or Python 3.12 type-alias handling used with Sphinx autodoc. Check how doc and comments after aliases are currently read. Done means aliases provide usable doc descriptions for generated widget parameters without breaking Sphinx autodoc.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100