From fe1642e85490bee6432aef3d29a39d337158fc09 Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Wed, 25 Dec 2019 22:54:15 -0500 Subject: [PATCH] Add special goto def/docs support in doom! blocks - Pressing gd on a module in your doom! block will now browse that module's directory. - Pressing K on a module will jump to that module's documentation, if any. - Pressing K on a module flag will jump to that flag's description within that module's documenation. - This is now explained in init.example.el Closes #2249 --- core/autoload/help.el | 32 +++++----- init.example.el | 18 ++++-- modules/editor/evil/README.org | 2 +- .../templates/org-mode/__doom-readme | 2 +- modules/lang/emacs-lisp/autoload.el | 64 ++++++++++++++++++- modules/lang/emacs-lisp/config.el | 2 +- 6 files changed, 93 insertions(+), 27 deletions(-) diff --git a/core/autoload/help.el b/core/autoload/help.el index 706f9406e..1e4d1fefb 100644 --- a/core/autoload/help.el +++ b/core/autoload/help.el @@ -335,13 +335,7 @@ without needing to check if they are available." readme-path))) (defun doom--help-current-module-str () - (cond ((and buffer-file-name - (eq major-mode 'emacs-lisp-mode) - (file-in-directory-p buffer-file-name doom-private-dir) - (save-excursion (goto-char (point-min)) - (re-search-forward "^\\s-*(doom! " nil t)) - (thing-at-point 'sexp t))) - ((save-excursion + (cond ((save-excursion (require 'smartparens) (ignore-errors (sp-beginning-of-sexp) @@ -360,11 +354,14 @@ without needing to check if they are available." (symbol-name (cadr mod))))))) ;;;###autoload -(defun doom/help-modules (category module) +(defun doom/help-modules (category module &optional visit-dir) "Open the documentation for a Doom module. CATEGORY is a keyword and MODULE is a symbol. e.g. :editor and 'evil. +If VISIT-DIR is non-nil, visit the module's directory rather than its +documentation. + Automatically selects a) the module at point (in private init files), b) the module derived from a `featurep!' or `require!' call, c) the module that the current file is in, or d) the module associated with the current major mode (see @@ -373,7 +370,8 @@ current file is in, or d) the module associated with the current major mode (see (mapcar #'intern (split-string (completing-read "Describe module: " - (doom--help-modules-list) nil t nil nil + (doom--help-modules-list) + nil t nil nil (doom--help-current-module-str)) " " t))) (cl-check-type category symbol) @@ -383,12 +381,16 @@ current file is in, or d) the module associated with the current major mode (see (user-error "'%s %s' is not a valid module" category module)) (unless (file-readable-p path) (error "Can't find or read %S module at %S" module-string path)) - (if (not (file-directory-p path)) - (find-file path) - (if (y-or-n-p (format "The %S module has no README file. Explore its directory?" - module-string)) - (doom-project-browse path) - (user-error "Aborted module lookup"))))) + (cond ((not (file-directory-p path)) + (if visit-dir + (doom-project-browse (file-name-directory path)) + (find-file path))) + (visit-dir + (doom-project-browse path)) + ((y-or-n-p (format "The %S module has no README file. Explore its directory?" + module-string)) + (doom-project-browse (file-name-directory path))) + ((user-error "Aborted module lookup"))))) ;; diff --git a/init.example.el b/init.example.el index 6bf9c773c..b25f89e30 100644 --- a/init.example.el +++ b/init.example.el @@ -1,12 +1,18 @@ ;;; init.el -*- lexical-binding: t; -*- -;; Copy this file to ~/.doom.d/init.el or ~/.config/doom/init.el ('doom install' -;; will do this for you). The `doom!' block below controls what modules are -;; enabled and in what order they will be loaded. Remember to run 'doom refresh' -;; after modifying it. +;; This file controls what Doom modules are enabled and what order they load in. +;; Remember to run 'doom sync' after modifying it! + +;; NOTE Press 'SPC h d h' (or 'C-h d h' for non-vim users) to access Doom's +;; documentation. There you'll find information about all of Doom's modules +;; and what flags they support. + +;; NOTE Move your cursor over a module's name (or its flags) and press 'K' (or +;; 'C-c g k' for non-vim users) to view its documentation. This works on +;; flags as well (those symbols that start with a plus). ;; -;; More information about these modules (and what flags they support) can be -;; found in modules/README.org. +;; Alternatively, press 'gd' (or 'C-c g d') on a module to browse its +;; directory (for easy access to its source code). (doom! :input ;;chinese diff --git a/modules/editor/evil/README.org b/modules/editor/evil/README.org index 38563af10..8c23d70f5 100644 --- a/modules/editor/evil/README.org +++ b/modules/editor/evil/README.org @@ -1,7 +1,7 @@ #+TITLE: feature/evil #+DATE: February 2, 2017 #+SINCE: v2.0 -#+STARTUP: inlineimages +#+STARTUP: inlineimages nofold * Table of Contents :TOC_3:noexport: - [[#description][Description]] diff --git a/modules/editor/file-templates/templates/org-mode/__doom-readme b/modules/editor/file-templates/templates/org-mode/__doom-readme index 8e8af8fa6..23b967bd3 100644 --- a/modules/editor/file-templates/templates/org-mode/__doom-readme +++ b/modules/editor/file-templates/templates/org-mode/__doom-readme @@ -8,7 +8,7 @@ "")`} #+DATE: `(format (format-time-string "%B %%s, %Y") (string-to-number (format-time-string "%d")))` #+SINCE: ${2:{replace with next tagged release version}} -#+STARTUP: inlineimages +#+STARTUP: inlineimages nofold * Table of Contents :TOC_3:noexport: diff --git a/modules/lang/emacs-lisp/autoload.el b/modules/lang/emacs-lisp/autoload.el index 2ee0a1c37..e16e66b0f 100644 --- a/modules/lang/emacs-lisp/autoload.el +++ b/modules/lang/emacs-lisp/autoload.el @@ -66,13 +66,71 @@ library/userland functions" (with-no-warnings (byte-compile #'+emacs-lisp-highlight-vars-and-faces))) + +(defun +emacs-lisp--module-at-point () + (let ((origin (point))) + (save-excursion + (goto-char (point-min)) + (when (re-search-forward "(doom! " nil 'noerror) + (goto-char (match-beginning 0)) + (cl-destructuring-bind (beg . end) + (bounds-of-thing-at-point 'sexp) + (when (and (>= origin beg) + (<= origin end)) + (goto-char origin) + (while (not (sexp-at-point)) + (forward-symbol -1)) + (let (category module flag) + (cond ((keywordp (setq category (sexp-at-point))) + (while (keywordp (sexp-at-point)) + (forward-sexp 1)) + (setq module (car (doom-enlist (sexp-at-point))))) + ((and (symbolp (setq module (sexp-at-point))) + (string-prefix-p "+" (symbol-name module))) + (while (symbolp (sexp-at-point)) + (beginning-of-sexp)) + (setq flag module + module (car (sexp-at-point))) + (when (re-search-backward "\\_<:\\w+\\_>" nil t) + (setq category (sexp-at-point)))) + ((symbolp module) + (when (re-search-backward "\\_<:\\w+\\_>" nil t) + (setq category (sexp-at-point))))) + (list category module flag)))))))) + +;;;###autoload +(defun +emacs-lisp-lookup-definition (thing) + "Lookup definition of THING." + (if-let (module (+emacs-lisp--module-at-point)) + (doom/help-modules (car module) (cadr module) 'visit-dir) + (call-interactively #'elisp-def))) + ;;;###autoload (defun +emacs-lisp-lookup-documentation (thing) "Lookup THING with `helpful-variable' if it's a variable, `helpful-callable' if it's callable, `apropos' otherwise." - (if thing - (doom/describe-symbol thing) - (call-interactively #'doom/describe-symbol))) + (cond ((when-let (module (+emacs-lisp--module-at-point thing)) + (doom/help-modules (car module) (cadr module)) + (when (eq major-mode 'org-mode) + (with-demoted-errors "%s" + (re-search-forward + (if (caddr module) + "\\* Module Flags$" + "\\* Description$")) + (when (caddr module) + (re-search-forward (format "=\\%s=" (caddr module)) + nil t)) + (when (invisible-p (point)) + (org-show-hidden-entry)))) + t)) + (thing (doom/describe-symbol thing)) + ((call-interactively #'doom/describe-symbol)))) + +;; FIXME +;; (defun +emacs-lisp-lookup-file (thing) +;; (when-let (module (+emacs-lisp--module-at-point thing)) +;; (doom/help-modules (car module) (cadr module) 'visit-dir) +;; t)) ;; diff --git a/modules/lang/emacs-lisp/config.el b/modules/lang/emacs-lisp/config.el index ef11526b3..a4224cf09 100644 --- a/modules/lang/emacs-lisp/config.el +++ b/modules/lang/emacs-lisp/config.el @@ -22,7 +22,7 @@ This marks a foldable marker for `outline-minor-mode' in elisp buffers.") (set-repl-handler! '(emacs-lisp-mode lisp-interaction-mode) #'+emacs-lisp/open-repl) (set-eval-handler! '(emacs-lisp-mode lisp-interaction-mode) #'+emacs-lisp-eval) (set-lookup-handlers! 'emacs-lisp-mode - :definition #'elisp-def + :definition #'+emacs-lisp-lookup-definition :documentation #'+emacs-lisp-lookup-documentation) (set-docsets! '(emacs-lisp-mode lisp-interaction-mode) "Emacs Lisp") (set-pretty-symbols! 'emacs-lisp-mode :lambda "lambda")