From cedbff090a7b17bd148ab67da7ce36a075450a15 Mon Sep 17 00:00:00 2001
From: Doug Davis <ddavis@anaconda.com>
Date: Mon, 20 Mar 2023 09:41:22 -0500
Subject: [PATCH 1/5] add unreleased section back
---
NEWS.md | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/NEWS.md b/NEWS.md
index 24fef1e..820b4ee 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,9 @@
# numpydoc.el NEWS -- history of user visible changes
+## Unreleased
+
+...
+
## 0.8 (March 20, 2023)
### Changes
From bccb0b08f96e035efd12af0ca415c474c52fcb45 Mon Sep 17 00:00:00 2001
From: Doug Davis <ddavis@anaconda.com>
Date: Mon, 20 Mar 2023 09:44:34 -0500
Subject: [PATCH 2/5] improve NEWS entry
---
NEWS.md | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/NEWS.md b/NEWS.md
index 820b4ee..e60b951 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -9,8 +9,10 @@
### Changes
- Add support for customizing ignored function arguments (function
- `Parameters` section). Contributed by
- [@pakelly](https://github.com/pakelley) in #13.
+ `Parameters` section) with new `defcustom`:
+ `numpydoc-ignored-params`. Contributed by
+ [@pakelly](https://github.com/pakelley) in
+ [#13](https://github.com/douglasdavis/numpydoc.el/pull/13).
## 0.7 (March 4, 2022)
From 935e6cb27ef278275dcf64dc603b58164848ab22 Mon Sep 17 00:00:00 2001
From: Doug Davis <ddavis@anaconda.com>
Date: Mon, 20 Mar 2023 10:42:01 -0500
Subject: [PATCH 3/5] tested versions update
---
.github/workflows/ci.yml | 4 +---
1 file changed, 1 insertion(+), 3 deletions(-)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5fc7575..7c9021c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -14,11 +14,9 @@ jobs:
strategy:
matrix:
emacs_version:
- - 25.1
- - 25.2
- - 25.3
- 26.3
- 27.2
+ - 28.2
steps:
- name: Setup GNU Emacs
From 5cb26db4f6b63a588ad7b8d2ec22ebf0f56f1076 Mon Sep 17 00:00:00 2001
From: Doug Davis <ddavis@anaconda.com>
Date: Mon, 24 Jul 2023 21:12:33 -0500
Subject: [PATCH 4/5] optionally auto fill paragraphs (#16)
---
NEWS.md | 9 +++++++--
README.md | 5 +++++
numpydoc.el | 18 ++++++++++++++----
3 files changed, 26 insertions(+), 6 deletions(-)
diff --git a/NEWS.md b/NEWS.md
index e60b951..8b3db60 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,8 +1,13 @@
# numpydoc.el NEWS -- history of user visible changes
-## Unreleased
+## 0.9 (July 24, 2023)
-...
+### Changes
+
+- Add new `defcustom`: `numpydoc-auto-fill-paragraphs`, which when set
+ to `t` (the default) will enable automatic paragraph filling for
+ (somewhat) long descriptions.
+ ([#16](https://github.com/douglasdavis/numpydoc.el/pull/16)).
## 0.8 (March 20, 2023)
diff --git a/README.md b/README.md
index 4ca3291..3c2d8f6 100644
--- a/README.md
+++ b/README.md
@@ -135,6 +135,11 @@ RET numpydoc</kbd>
All function parameters with names listed here will be ignored
when generating a docstring.
</dd>
+ <dt>numpydoc-auto-fill-paragraphs</dt>
+ <dd>
+ If <code>t</code> text that is inserted in a prompt will be
+ automatically paragraph-filled.
+ </dd>
</dl>
## Examples
diff --git a/numpydoc.el b/numpydoc.el
index 87954b4..caa99ee 100644
--- a/numpydoc.el
+++ b/numpydoc.el
@@ -6,7 +6,7 @@
;; Maintainer: Doug Davis <ddavis@ddavis.io>
;; URL: https://github.com/douglasdavis/numpydoc.el
;; SPDX-License-Identifier: GPL-3.0-or-later
-;; Version: 0.8
+;; Version: 0.9
;; Package-Requires: ((emacs "25.1") (s "1.12.0") (dash "2.18.0"))
;; Keywords: convenience
@@ -133,6 +133,13 @@ when generating a docstring."
:group 'numpydoc
:type '(repeat string))
+(defcustom numpydoc-auto-fill-paragraphs t
+ "Flag to control automatic paragraph filling.
+If set to t text that is inserted in a prompt will be automatically
+paragraph-filled."
+ :group 'numpydoc
+ :type 'boolean)
+
;;; package implementation code.
(cl-defstruct numpydoc--def
@@ -391,7 +398,8 @@ This function assumes the cursor to be in the function body."
(unless (string-empty-p ld)
(insert "\n")
(numpydoc--insert indent ld)
- (numpydoc--fill-last-insertion)
+ (when numpydoc-auto-fill-paragraphs
+ (numpydoc--fill-last-insertion))
(insert "\n")))
(insert "\n")
(numpydoc--insert indent tmpl)
@@ -429,7 +437,8 @@ This function assumes the cursor to be in the function body."
element))
tmpd))))
(numpydoc--insert indent desc)
- (numpydoc--fill-last-insertion)
+ (when numpydoc-auto-fill-paragraphs
+ (numpydoc--fill-last-insertion))
(insert "\n")))
(defun numpydoc--insert-parameters (indent fnargs)
@@ -466,7 +475,8 @@ This function assumes the cursor to be in the function body."
(if (numpydoc--prompt-p)
(read-string "Description for return: ")
tmpr)))
- (numpydoc--fill-last-insertion)
+ (when numpydoc-auto-fill-paragraphs
+ (numpydoc--fill-last-insertion))
(insert "\n"))))
(defun numpydoc--insert-exceptions (indent fnexcepts)
From 77e2893442c6e20af9c99b9ba2c6c11988fe0e80 Mon Sep 17 00:00:00 2001
From: Doug Davis <ddavis@anaconda.com>
Date: Fri, 11 Aug 2023 12:08:22 -0500
Subject: [PATCH 5/5] Emit a meaningful error if function signature parsing
fails (#18)
---
NEWS.md | 7 ++++++
numpydoc.el | 61 ++++++++++++++++++++++++++++-------------------------
2 files changed, 39 insertions(+), 29 deletions(-)
diff --git a/NEWS.md b/NEWS.md
index 8b3db60..4e60b36 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,12 @@
# numpydoc.el NEWS -- history of user visible changes
+## Unreleased
+
+### Changes
+
+- Emit a useful warning if function signature parsing fails
+ ([#18](https://github.com/douglasdavis/numpydoc.el/pull/18)).
+
## 0.9 (July 24, 2023)
### Changes
diff --git a/numpydoc.el b/numpydoc.el
index caa99ee..198cd9c 100644
--- a/numpydoc.el
+++ b/numpydoc.el
@@ -256,35 +256,38 @@ This function assumes the cursor to be in the function body."
(defun numpydoc--parse-def (buffer-substr)
"Parse the BUFFER-SUBSTR; return instance of numpydoc--def."
(save-excursion
- (let* ((fnsig buffer-substr)
- ;; trimmed string of the function signature
- (trimmed (s-collapse-whitespace fnsig))
- ;; split into parts (args and return type)
- (parts (s-split "->" trimmed))
- ;; raw return
- (rawret (if (nth 1 parts)
- (s-trim (nth 1 parts))
- nil))
- ;; save return type as a string (or nil)
- (rtype (when rawret
- (substring rawret 0 (1- (length rawret)))))
- ;; raw signature without return type as a string
- (rawsig (cond (rtype (substring (s-trim (car parts)) 0 -1))
- (t (substring (s-trim (car parts)) 0 -2))))
- ;; function args as strings
- (rawargs (-map #'s-trim
- (numpydoc--split-args
- (substring rawsig
- (1+ (string-match-p (regexp-quote "(")
- rawsig))))))
- ;; function args as a list of structures (remove some special cases)
- (args (-remove (lambda (x)
- (-contains-p numpydoc-ignored-params
- (numpydoc--arg-name x)))
- (-map #'numpydoc--arg-str-to-struct rawargs)))
- ;; look for exceptions in the function body
- (exceptions (numpydoc--find-exceptions)))
- (make-numpydoc--def :args args :rtype rtype :raises exceptions))))
+ (condition-case nil
+ (progn
+ (let* ((fnsig buffer-substr)
+ ;; trimmed string of the function signature
+ (trimmed (s-collapse-whitespace fnsig))
+ ;; split into parts (args and return type)
+ (parts (s-split "->" trimmed))
+ ;; raw return
+ (rawret (if (nth 1 parts)
+ (s-trim (nth 1 parts))
+ nil))
+ ;; save return type as a string (or nil)
+ (rtype (when rawret
+ (substring rawret 0 (1- (length rawret)))))
+ ;; raw signature without return type as a string
+ (rawsig (cond (rtype (substring (s-trim (car parts)) 0 -1))
+ (t (substring (s-trim (car parts)) 0 -2))))
+ ;; function args as strings
+ (rawargs (-map #'s-trim
+ (numpydoc--split-args
+ (substring rawsig
+ (1+ (string-match-p (regexp-quote "(")
+ rawsig))))))
+ ;; function args as a list of structures (remove some special cases)
+ (args (-remove (lambda (x)
+ (-contains-p numpydoc-ignored-params
+ (numpydoc--arg-name x)))
+ (-map #'numpydoc--arg-str-to-struct rawargs)))
+ ;; look for exceptions in the function body
+ (exceptions (numpydoc--find-exceptions)))
+ (make-numpydoc--def :args args :rtype rtype :raises exceptions)))
+ (error "Failed to parse function signature (bad Python syntax)."))))
(defun numpydoc--has-existing-docstring-p ()
"Check for an existing docstring.