v1.7.1 - Newline Removed Between :raises : and :param : Documentation

[rmartin16]

With v1.7.1, some newlines are being removed between :raises : and :param : documentation.

@@ -3,7 +3,6 @@ def search_delete(self, search_id=None, **kwargs):
     Delete a search job.
 
     :raises NotFound404Error: 
-
     :param search_id: ID of search to delete
     :return: None
     """

Although, this one is not reformatted:

def rss_mark_as_read(self, item_path=None, article_id=None, **kwargs):
    """
    Mark RSS article as read. If article ID is not provider, the entire feed is marked
    as read.

    :raises NotFound404Error:

    :param item_path: path to item to be refreshed (e.g. ``Folder\\Subfolder\\ItemName``)
    :param article_id: article ID from :meth:`~RSSAPIMixIn.rss_items`
    :return: None
    """

Config:

  - repo: https://github.com/PyCQA/docformatter
    rev: v1.7.1
    hooks:
      - id: docformatter
        args: [--in-place, --pre-summary-newline, --black]

more examples: rmartin16/qbittorrent-api#210

[weibullguy]

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:

1. Keep it as is and make you upset because of all those wasted Return keystrokes.
2. Automatically group like-type field lists (i.e., all raises grouped, all param grouped) and place a newline between each group. That'll probably upset someone else.
3. Choose one of the above as the default and provide an argument to 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.

[rmartin16]

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 :raises : documentation without content after the closing colon. [edit: not the case]

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.

[weibullguy]

@rmartin16 this should be fixed in v1.7.3-rc1. I finally decided not to do anything fancy and just retain newlines as is.