emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

tools/lookup: update README & docstrings

Browse source 
And minor reformatting of config.el
This commit is contained in:
Henrik Lissner 2019-05-03 20:44:23 -04:00
parent 96ca04d488
commit d481fc1dd4
No known key found for this signature in database
GPG key ID: 5F6C0EA160557395
2 changed files with 71 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

100
modules/tools/lookup/README.org
View file

@ -4,22 +4,24 @@
#+STARTUP: inlineimages
* Table of Contents :TOC:
- [[Description][Description]]
- [[Module Flags][Module Flags]]
- [[Plugins][Plugins]]
- [[Install][Install]]
- [[Module flags][Module flags]]
- [[Dependencies][Dependencies]]
- [[Features][Features]]
- [[Jump to definition][Jump to definition]]
- [[Find references][Find references]]
- [[Look up documentation][Look up documentation]]
- [[Search a specific documentation backend][Search a specific documentation backend]]
- [[Configuration][Configuration]]
- [[Settings][Settings]]
- [[Open in eww instead of browser][Open in eww instead of browser]]
- [[Appendix][Appendix]]
- [[Commands][Commands]]
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#macos][MacOS]]
- [[#arch-linux][Arch Linux]]
- [[#features][Features]]
- [[#jump-to-definition][Jump to definition]]
- [[#find-references][Find references]]
- [[#look-up-documentation][Look up documentation]]
- [[#search-a-specific-documentation-backend][Search a specific documentation backend]]
- [[#dashapp-docset-integration][Dash.app Docset integration]]
- [[#configuration][Configuration]]
- [[#associating-lookup-handlers-with-major-modes][Associating lookup handlers with major modes]]
- [[#associating-dash-docsets-with-major-modes][Associating Dash docsets with major modes]]
- [[#open-in-eww-instead-of-browser][Open in eww instead of browser]]
- [[#appendix][Appendix]]
- [[#commands][Commands]]
* Description
Integrates with code navigation and documentation tools to help you quickly look
@ -39,35 +41,26 @@ up definitions, references and documentation.
+ [[https://github.com/alexmurray/ivy-xref][ivy-xref]] or [[https://github.com/brotzeit/helm-xref][helm-xref]]
+ [[https://github.com/nathankot/counsel-dash][counsel-dash]] or [[https://github.com/areina/helm-dash][helm-dash]]
* Install
To enable the module add =:tools lookup= to your ~doom!~ block in
=~/.emacs.d/init.el=.
** Module flags
This module provides two flags:
+ ~+docsets~ Enables integration with Dash docsets.
** Dependencies
* Prerequisites
This module has several soft dependencies:
+ ~the_silver_searcher~ and/or ~ripgrep~ as a last-resort fallback for
+ ~the_silver_searcher~ or ~ripgrep~ (recommended) as a last-resort fallback for
jump-to-definition/find-references.
+ Optionally, ~sqlite3~ for Dash docset support.
+ ~sqlite3~ for Dash docset support.
*** MacOS
** MacOS
#+BEGIN_SRC sh
brew install the_silver_searcher ripgrep
# An older version of sqlite is included in MacOS. If it causes you problems (and
# it has been reported that it will), install it through homebrew:
# folks have reported it will), install it through homebrew:
brew install sqlite
# Note that it's keg-only, meaning it isn't symlinked to /usr/local/bin. You'll
# have to add it to PATH yourself (or symlink it into your PATH somewhere). e.g.
export PATH="/usr/local/opt/sqlite/bin:$PATH"
#+END_SRC
*** Arch Linux
** Arch Linux
#+BEGIN_SRC sh
sudo pacman -S sqlite the_silver_searcher ripgrep
#+END_SRC
@ -121,17 +114,21 @@ Depending on your configuration, this will try a list of sources:
You can perform a documentation lookup on any backends directly:
+ Dash Docsets: ~+lookup/in-docsets~, or ~:dash QUERY~ for evil users.
+ devdocs.io: ~+lookup/in-devdocs~, or ~:dd QUERY~ for evil users.
+ Online (generic): ~+lookup/online~ or ~+lookup/online-select~ (bound to =SPC /
o=), or ~:lo[okup] QUERY~ for evil users.
* Configuration
** Settings
This module provides two setters:
** Dash.app Docset integration
You can install dash docsets with ~M-x +lookup/install-docset~ and search them
offline with ~M-x +lookup/in-docsets~, or with ~+lookup/documentation~ in modes
that don't have a specialized :documentation lookup handler.
*** ~set-lookup-handlers! MODES &rest PLIST~
Defines a lookup target for major MODES (one major-mode symbol or a list
thereof). PLIST accepts the following optional properties:
* Configuration
** Associating lookup handlers with major modes
~set-lookup-handlers! MODES &key DEFINITION REFERENCES DOCUMENTATION FILE XREF-BACKEND ASYNC~
Use ~set-lookup-handlers!~ to register lookup targets for MODES (a major or
minor mode symbol or list thereof). PLIST accepts the following optional
properties:
+ ~:definition FN~ :: Run when jumping to a symbol's definition. Used by
~+lookup/definition~.
@ -141,10 +138,11 @@ thereof). PLIST accepts the following optional properties:
~+lookup/documentation~.
+ ~:file FN~ :: Run when looking up the file for a symbol/string. Typically a
file path. Used by ~+lookup/file~.
+ ~:xref-backend FN~ :: Defines an xref backend for a major-mode. With this,
:definition and :references are unnecessary.
+ ~:xref-backend FN~ :: Defines an xref backend, which implicitly provides
:definition and :references handlers. If you specify them anyway, they will
take precedence over the xref backend, however.
**** Example
e.g.
#+BEGIN_SRC emacs-lisp
;; For python-mode, anaconda-mode offers a backend for all three lookup
;; functions. We can register them like so:
@ -160,11 +158,14 @@ thereof). PLIST accepts the following optional properties:
;; NOTE: xref doesn't provide a :documentation backend.
#+END_SRC
*** ~set-docsets! MODES &rest DOCSETS~
Registers DOCSETS (one string or list of strings) for MODES (one major mode
symbol or a list of them). It is used by ~+lookup/in-docsets~ and
~+lookup/documentation~.
** Associating Dash docsets with major modes
~set-docsets! MODES &rest DOCSETS...~
Use ~set-docsets!~ to register DOCSETS (one string or list of strings) for MODES
(one major mode symbol or a list of them). It is used by ~+lookup/in-docsets~
and ~+lookup/documentation~.
e.g.
#+BEGIN_SRC emacs-lisp
(set-docsets! 'js2-mode "JavaScript" "JQuery")
;; Add docsets to minor modes by starting DOCSETS with :add
@ -173,9 +174,16 @@ symbol or a list of them). It is used by ~+lookup/in-docsets~ and
(set-docsets! 'nodejs-mode :remove "JQuery")
#+END_SRC
This determines what docsets to implicitly search for when you use
~+lookup/documentation~ in a mode with no ~:documentation~ handler. Those
docsets must be installed with ~+lookup/install-docset~.
** Open in eww instead of browser
To open results from ~+lookup/online~ in EWW instead of your system browser,
change ~+lookup-open-url-fn~ (default: ~#'browse-url~):
#+BEGIN_SRC emacs-lisp
(setq +lookup-open-url-fn 'eww)
(setq +lookup-open-url-fn #'eww)
#+END_SRC
* Appendix

30
modules/tools/lookup/config.el
View file

@ -41,7 +41,8 @@ window/point.
If the argument is interactive (satisfies `commandp'), it is called with
`call-interactively' (with no arguments). Otherwise, it is called with one
argument: the identifier at point.")
argument: the identifier at point. See `set-lookup-handlers!' about adding to
this list.")
(defvar +lookup-references-functions
'(+lookup-xref-references-backend
@ -52,7 +53,8 @@ window/point.
If the argument is interactive (satisfies `commandp'), it is called with
`call-interactively' (with no arguments). Otherwise, it is called with one
argument: the identifier at point.")
argument: the identifier at point. See `set-lookup-handlers!' about adding to
this list.")
(defvar +lookup-documentation-functions
'(+lookup-dash-docsets-backend
@ -63,7 +65,8 @@ window/point.
If the argument is interactive (satisfies `commandp'), it is called with
`call-interactively' (with no arguments). Otherwise, it is called with one
argument: the identifier at point.")
argument: the identifier at point. See `set-lookup-handlers!' about adding to
this list.")
(defvar +lookup-file-functions ()
"Function for `+lookup/file' to try, before restoring to `find-file-at-point'.
@ -72,7 +75,8 @@ window/point.
If the argument is interactive (satisfies `commandp'), it is called with
`call-interactively' (with no arguments). Otherwise, it is called with one
argument: the identifier at point.")
argument: the identifier at point. See `set-lookup-handlers!' about adding to
this list.")
;;
@ -97,19 +101,19 @@ argument: the identifier at point.")
;; We already have `projectile-find-tag' and `evil-jump-to-tag', no need for
;; xref to be one too.
(remove-hook 'xref-backend-functions #'etags--xref-backend)
;; ...however, it breaks `projectile-find-tag', unless we put it back.
(defun +lookup*projectile-find-tag (orig-fn)
(let ((xref-backend-functions '(etags--xref-backend t)))
(funcall orig-fn)))
(advice-add #'projectile-find-tag :around #'+lookup*projectile-find-tag)
;; The lookup commands are superior, and will consult xref if there are no
;; better backends available.
(global-set-key [remap xref-find-definitions] #'+lookup/definition)
(global-set-key [remap xref-find-references] #'+lookup/references))
(global-set-key [remap xref-find-references] #'+lookup/references)
;; Use `better-jumper' instead of xref's marker stack
(advice-add #'xref-push-marker-stack :around #'doom*set-jump)
;; ...however, it breaks `projectile-find-tag', unless we put it back.
(defun +lookup*projectile-find-tag (orig-fn)
(let ((xref-backend-functions '(etags--xref-backend t)))
(funcall orig-fn)))
(advice-add #'projectile-find-tag :around #'+lookup*projectile-find-tag)
;; Use `better-jumper' instead of xref's marker stack
(advice-add #'xref-push-marker-stack :around #'doom*set-jump))
(def-package! ivy-xref