Inconsistent formatting of parameter descriptions depending on whether they have one or multiple paragraphs
#4 227 ouverte le 8 nov. 2017
Métriques du dépôt
- Stars
- (5 625 stars)
- Métriques de merge PR
- (Merge moyen 10j 11h) (11 PRs mergées en 30 j)
Description
Subject: Inconsistent formatting of parameter descriptions depending on whether they have one or multiple paragraphs
Problem
Descriptions of parameters that have a single paragraph start on the same line as the parameter name and type, whereas descriptions of parameters that have multiple paragraphs start on a new line, creating an inconsistent layout.
Procedure to reproduce the problem
autodoc the following using a default environment.
def f(x, y):
"""
:param x:
The foo.
:type x: int
:param y: The other foo.
But with two paragraphs.
:type y: int
"""
Error logs / results
Expected results
Either consistently start the first line of the param description on the same line as the parameter name, or consistently start it on the line below. (The old behavior could be maintained as available using a config switch.)
Possibly better would be to stay on the same line if all param descriptions (for a given signature) are single-paragraph, and always start a new line as long as at least one param has multiple paragraphs.
Reproducible project / your project
- N/A
Environment info
- OS: Linux
- Python version: 3.6
- Sphinx version: 1.6.5