Closed rmartin16 closed 1 year ago
I think I've taken care of your other issues in #215, #218, and #219. Tag v1.7.2-rc1 has the fixes if you'd like to give it a try. Feedback would be appreciated.
For this issue, commit cb7bf8d introduced code to handle wrapping of long descriptions in field lists with the :param name: description
pattern. Currently that, obviously, doesn't retain newlines. I'm pondering three options:
Return
keystrokes.raises
grouped, all param
grouped) and place a newline between each group. That'll probably upset someone else.docformatter
for those users who prefer the the non-default option. This'll probably upset everyone because they'll have to contend with a new argument.I'm leaning towards 3 with 2 being the default behavior because I think that could be helpful behavior when I tackle Numpy and Google style field lists.
Hmm...would it be possible to retain (or collapse to) a single newline if any exist? I imagine there may be something in the implementation preventing this...although, it also seems the newlines are only being removed right now for [edit: not the case]:raises :
documentation without content after the closing colon.
I'd be fine with any of those options. The grouping seems (at least naively) a bit intrusive....if someone, for instance, has logically grouped a certain param
with a certain raises
; although, such ordering isn't likely to be represented in the rendered Sphinx docs....which is what most of this matters for anyway.
P.S. I'm also noticing an extra space being added after the closing colon if additional content doesn't follow it. This upsets black
because it is perceived as a trailing space.
@rmartin16 this should be fixed in v1.7.3-rc1. I finally decided not to do anything fancy and just retain newlines as is.
With v1.7.1, some newlines are being removed between
:raises :
and:param :
documentation.Although, this one is not reformatted:
Config:
more examples: https://github.com/rmartin16/qbittorrent-api/pull/210