Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
xmo-odoo opened this issue Apr 5, 2024 · 3 comments
Labels
C: stakeholder Relates to docformatter stakeholder requested behavior P: enhancement Feature that is outside the scope of PEP 257 U: low A relatively low urgency issue

Comments

@xmo-odoo
Copy link

xmo-odoo commented Apr 5, 2024

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.
@github-actions github-actions bot added the fresh This is a new issue label Apr 5, 2024
@EnricoMi
Copy link

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

@EnricoMi
Copy link

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
Copy link
Author

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

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.

@weibullguy weibullguy added P: enhancement Feature that is outside the scope of PEP 257 C: stakeholder Relates to docformatter stakeholder requested behavior and removed fresh This is a new issue labels Jul 31, 2024
@github-actions github-actions bot added the U: low A relatively low urgency issue label Jul 31, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C: stakeholder Relates to docformatter stakeholder requested behavior P: enhancement Feature that is outside the scope of PEP 257 U: low A relatively low urgency issue
Projects
None yet
Development

No branches or pull requests

3 participants