docformatter seems to have trouble with linebreaks inside directives in info fields

[xmo-odoo]

Saw this issue in PyGithub docstrings, when I fix it docformatter complains about exactly what I'm fixing:

diff --git a/github/Repository.py b/github/Repository.py
index f274973..52bcc11 100644
--- a/github/Repository.py
+++ b/github/Repository.py
@@ -2388,7 +2388,7 @@ class Repository(CompletableGithubObject):
         Create a file in this repository.
 
         :calls: `PUT /repos/{owner}/{repo}/contents/{path} <https://docs.github.com/en/rest/reference/repos#create-or-
-            update-file-contents>`_
+        update-file-contents>`_
         :param path: string, (required), path of the file in the repository
         :param message: string, (required), commit message
         :param content: string, (required), the actual data in the file
@@ -2470,7 +2470,7 @@ class Repository(CompletableGithubObject):
         This method updates a file in a repository.
 
         :calls: `PUT /repos/{owner}/{repo}/contents/{path} <https://docs.github.com/en/rest/reference/repos#create-or-
-            update-file-contents>`_
+        update-file-contents>`_
         :param path: string, Required. The content path.
         :param message: string, Required. The commit message.
         :param content: string, Required. The updated file content, either base64 encoded, or 

Trying to remove the linebreak instead of indenting it also makes docformatter amgy:

diff --git a/github/Repository.py b/github/Repository.py
index d7e3c19..52bcc11 100644
--- a/github/Repository.py
+++ b/github/Repository.py
@@ -2387,7 +2387,8 @@ class Repository(CompletableGithubObject):
         """
         Create a file in this repository.
 
-        :calls: `PUT /repos/{owner}/{repo}/contents/{path} <https://docs.github.com/en/rest/reference/repos#create-or-update-file-contents>`_
+        :calls: `PUT /repos/{owner}/{repo}/contents/{path} <https://docs.github.com/en/rest/reference/repos#create-or-
+        update-file-contents>`_
         :param path: string, (required), path of the file in the repository
         :param message: string, (required), commit message
         :param content: string, (required), the actual data in the file
@@ -2468,7 +2469,8 @@ class Repository(CompletableGithubObject):
         """
         This method updates a file in a repository.
 
-        :calls: `PUT /repos/{owner}/{repo}/contents/{path} <https://docs.github.com/en/rest/reference/repos#create-or-update-file-contents>`_
+        :calls: `PUT /repos/{owner}/{repo}/contents/{path} <https://docs.github.com/en/rest/reference/repos#create-or-
+        update-file-contents>`_
         :param path: string, Required. The content path.
         :param message: string, Required. The commit message.
         :param content: string, Required. The updated file content, either base64 encoded, or ready to be encoded.

[EnricoMi]

The sphinx doc build is fine with the indentation, so docformatter should be happy with it.

[EnricoMi]

The problem is that our docstring uses a custom field (calls) which are not recognized by the SPHINX_REGEX. We would have to add that bespoke field to the regex.

[xmo-odoo]

Seems odd to be using a regex for something that's potentially open-ended, even more so when the list isn't complete:

docformatter/src/docformatter/syntax.py

Line 62 in 504107b

SPHINX_REGEX = r":(param|raises|return|rtype|type|yield)[a-zA-Z0-9_\-.() ]*:"

but as of sphinx 3 this is already missing:

• arg(ument)
• key(word)
• meta

And it has yield which does not seem to be a standard info field.