convention when return can be either float or array
Open
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
I have a vectorized function. If scalars are passed as inputs, the output is scalar. If some selected (vectorized) inputs have dimension > 0, the output is array. How to document this? I have tried something like:
Returns
=======
If input `lat`, `lon` or `height` have dimension > 0, outputs are arrays.
lat : float or array
Latitude
lon : float or array
Longitude
However, when the docs are built (at least on readthedocs), everything in the Returns section is interpreted as outputs, including the note at the start. See the image below:
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
Start with the issue's Returns-section example and reproduce its rendering on ReadTheDocs. Review how numpydoc interprets the section, then document a convention for scalar-or-array outputs that renders the explanatory note correctly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100