Skip to content

Adds defcustom numpydoc-newline-after-opening-quotes #20

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.

Sign up for GitHub

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Adds defcustom numpydoc-newline-after-opening-quotes #20

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
705c94e
Adds defcustom numpydoc-newline-after-opening-quotes
slackline Jan 3, 2024
001d76b
default numpydoc-newline-after-opening-quotes to nil
slackline Nov 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion numpydoc.el
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,13 @@ paragraph-filled."
:group 'numpydoc
:type 'boolean)

(defcustom numpydoc-newline-after-opening-quotes t
"Flag to control insertion of newline after the opening quotes.
If set to t a newline will be inserted after the opening quotes of
the docstring to comply with numpydoc validation rule GL01."
:group 'numpydoc
:type 'boolean)

;;; package implementation code.

(cl-defstruct numpydoc--def
Expand Down Expand Up @@ -385,10 +392,12 @@ This function assumes the cursor to be in the function body."
(insert "\n")
(numpydoc--insert indent
(concat (make-string 3 numpydoc-quote-char)
(if numpydoc-newline-after-opening-quotes
"\n ")
Copy link
Owner

@douglasdavis douglasdavis Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does numpydoc--insert with indent not take care of the extra spaces? (I haven't tested the code so I'm asking here)

Copy link
Author

@slackline slackline Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean indenting to align with the docstring indent i.e. there may be no need for the spaces after the carriage return?

Suggested change
"\n ")
"\n")

Not sure, I'll check it out and report back.

Copy link
Author

@slackline slackline Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked this, if the spaces aren't there then the text isn't indented to align with the start of the """ so I think they are required, but appreciate there is likely a smarter way of doing this.

Looking at the code (not being very conversant in Emacs Lisp) it looks like its numpydoc--insert that is required.

I tried adding

Suggested change
"\n ")
"\n"
(numpydoc--insert indent ld))

..without any success, insert Short Description was at the start of the line. Then I realised there is numpydoc--insert-short-and-long-desc defined right after numpydoc--insert which only takes indent as an argument so tried...

Suggested change
"\n ")
"\n"
(numpydoc--insert-short-and-long-desc indent))

Next I tried placing it outside if the surrounding (if numpydoc-newline-afer-opening-quote-char "\n")

Suggested change
"\n ")
"\n")
(numpydoc--insert-short-and-long-desc indent)

...which didn't work either, it resulted in exceeding the nesting max-lisp-eval-depth, I think because that causes the function to be called recursively without any break-out clause!

Looking further down I see that the "Long description" I think the following...

    (if (numpydoc--prompt-p)
        (progn
          (setq ld (read-string (concat "Long description "
                                        "(or press return to skip): ")
                                nil nil "" nil))   ;; This captures the text to be inserted
          (unless (string-empty-p ld)
            (insert "\n")
            (numpydoc--insert indent ld)  ;; This inserts the value of ld
            (when numpydoc-auto-fill-paragraphs   ;; auto-fill/wrap paragraphs
              (numpydoc--fill-last-insertion))
            (insert "\n")))
      (insert "\n")
      (numpydoc--insert indent tmpl)
      (insert "\n"))))

So I tried using that as a template....

    (numpydoc--insert indent
                      (concat (make-string 3 numpydoc-quote-char)
                              (if numpydoc-newline-after-opening-quotes
                                "\n")
                              (if (numpydoc--prompt-p)
                                (progn
                                  (setq ld (read-string (format "Short description: ")
                                             tmps))
                                  (unless (string-empty-p ld)
                                    (insert "\n")
                                    (numpydoc--insert indent ld)
                                    (when numpydoc-auto-fill-paragraphs
                                      (numpydoc--fill-last-insertion))
                                    (insert "\n")))
                                (insert "\n")
                      (make-string 3 numpydoc-quote-char))

No dice, feel like I'm out of my depth here but keen to learn what it is I'm missing/not understanding.

(if (numpydoc--prompt-p)
(read-string
(format "Short description: "))
tmps)
tmps)
"\n\n")
(make-string 3 numpydoc-quote-char))
(forward-line -1)
Expand Down