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

@@ -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
+  (cond ((save-excursion
-              (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
            (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))
+    (cond ((not (file-directory-p path))
-        (find-file path)
+           (if visit-dir
-      (if (y-or-n-p (format "The %S module has no README file. Explore its directory?"
+               (doom-project-browse (file-name-directory path))
-                            module-string))
+             (find-file path)))
-          (doom-project-browse path)
+          (visit-dir
-        (user-error "Aborted module lookup")))))
+           (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")))))
 
 
 ;;

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'
+;; This file controls what Doom modules are enabled and what order they load in.
-;; will do this for you). The `doom!' block below controls what modules are
+;; Remember to run 'doom sync' after modifying it!
-;; enabled and in what order they will be loaded. Remember to run 'doom refresh'
+
-;; 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
+;;      Alternatively, press 'gd' (or 'C-c g d') on a module to browse its
-;; found in modules/README.org.
+;;      directory (for easy access to its source code).
 
 (doom! :input
        ;;chinese

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]]

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:
 

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
+  (cond ((when-let (module (+emacs-lisp--module-at-point thing))
-      (doom/describe-symbol thing)
+           (doom/help-modules (car module) (cadr module))
-    (call-interactively #'doom/describe-symbol)))
+           (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))
 
 
 ;;

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")