merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -1,74 +1,72 @@
|
|||
#+TITLE: tools/lookup
|
||||
#+DATE: January 4, 2018
|
||||
#+SINCE: v2.0.9
|
||||
#+STARTUP: inlineimages
|
||||
# -*- mode: doom-docs-org -*-
|
||||
#+title: :tools lookup
|
||||
#+subtitle: Navigate your labyrinthine code and docs
|
||||
#+created: January 04, 2018
|
||||
#+since: 2.0.9
|
||||
|
||||
* Table of Contents :TOC:
|
||||
- [[#description][Description]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#macos][MacOS]]
|
||||
- [[#arch-linux][Arch Linux]]
|
||||
- [[#nixos][NixOS]]
|
||||
- [[#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]]
|
||||
- [[#open-in-xwidget-webkit-instead-of-browser][Open in Xwidget WebKit instead of browser]]
|
||||
- [[#appendix][Appendix]]
|
||||
- [[#commands][Commands]]
|
||||
|
||||
* Description
|
||||
* Description :unfold:
|
||||
This module adds code navigation and documentation lookup tools to help you
|
||||
quickly look up definitions, references, documentation, dictionary definitions
|
||||
or synonyms.
|
||||
|
||||
+ Jump-to-definition and find-references implementations that just work.
|
||||
+ Powerful xref integration for languages that support it.
|
||||
+ Search online providers like devdocs.io, stackoverflow, google, duckduckgo or
|
||||
youtube (duckduckgo and google have live suggestions).
|
||||
+ Integration with Dash.app docsets.
|
||||
+ Support for online (and offline) dictionaries and thesauruses.
|
||||
- Jump-to-definition and find-references implementations that just work.
|
||||
- Powerful xref integration for languages that support it.
|
||||
- Search online providers like [[https://devdocs.io][devdocs.io]], [[https://stackoverflow.com][stackoverflow]], [[https://google.com][google]], [[https://duckduckgo.com][duckduckgo]], or
|
||||
[[https://youtube.com][youtube]] (duckduckgo and google have live suggestions).
|
||||
- Integration with [[https://github.com/Kapeli/feeds][Dash.app docsets]].
|
||||
- Support for online (and offline) dictionaries and thesauruses.
|
||||
|
||||
** Module Flags
|
||||
+ ~+dictionary~ Enable word definition and thesaurus lookup functionality.
|
||||
+ ~+offline~ Install and prefer offline dictionary/thesaurus.
|
||||
+ ~+docsets~ Enable integration with Dash.app docsets.
|
||||
** Maintainers
|
||||
- [[doom-user:][@hlissner]]
|
||||
|
||||
** Plugins
|
||||
+ [[https://github.com/jacktasia/dumb-jump][dumb-jump]]
|
||||
+ [[https://github.com/alexmurray/ivy-xref][ivy-xref]] or [[https://github.com/brotzeit/helm-xref][helm-xref]]
|
||||
+ [[https://github.com/tkf/emacs-request][request]]
|
||||
+ =+docsets=
|
||||
+ [[https://github.com/dash-docs-el/dash-docs][dash-docs]]
|
||||
+ [[https://github.com/nathankot/counsel-dash][counsel-dash]] or [[https://github.com/areina/helm-dash][helm-dash]]
|
||||
+ =+dictionary=
|
||||
+ if macOS
|
||||
+ [[https://github.com/xuchunyang/osx-dictionary.el][osx-dictionary]]* (on macOS)
|
||||
+ else
|
||||
+ [[https://github.com/abo-abo/define-word][define-word]]
|
||||
+ [[https://github.com/maxchaos/emacs-powerthesaurus][powerthesaurus]]
|
||||
+ =+offline=
|
||||
+ [[https://github.com/gromnitsky/wordnut][wordnut]]
|
||||
+ [[https://github.com/hpdeifel/synosaurus][synosaurus]]
|
||||
[[doom-contrib-maintainer:][Become a maintainer?]]
|
||||
|
||||
* Prerequisites
|
||||
This module has several soft dependencies:
|
||||
** Module flags
|
||||
- +dictionary ::
|
||||
Enable word definition and thesaurus lookup functionality.
|
||||
- +docsets ::
|
||||
Enable integration with Dash.app docsets.
|
||||
- +offline ::
|
||||
Install and prefer offline dictionary/thesaurus (with [[doom-module:][+dictionary]]).
|
||||
|
||||
+ ~ripgrep~ as a last-resort fallback for jump-to-definition/find-references.
|
||||
+ ~sqlite3~ for Dash docset support (if you have =+docsets= enabled)
|
||||
+ ~wordnet~ for offline dictionary and thesaurus support (if you have
|
||||
=+dictionary +offline= enabled).
|
||||
** Packages
|
||||
- [[doom-package:][dumb-jump]]
|
||||
- [[doom-package:][helm-xref]] if [[doom-module:][:completion helm]]
|
||||
- [[doom-package:][ivy-xref]] if [[doom-module:][:completion ivy]]
|
||||
- [[doom-package:][request]]
|
||||
- if [[doom-module:][+docsets]]
|
||||
- [[doom-package:][dash-docs]]
|
||||
- [[doom-package:][counsel-dash]] if [[doom-module:][:completion ivy]]
|
||||
- [[doom-package:][helm-dash]] if [[doom-module:][:completion helm]]
|
||||
- if [[doom-module:][+dictionary]]
|
||||
- if macOS
|
||||
- [[doom-package:][osx-dictionary]]
|
||||
- else
|
||||
- [[doom-package:][define-word]]
|
||||
- [[doom-package:][powerthesaurus]]
|
||||
- if [[doom-module:][+offline]]
|
||||
- [[doom-package:][wordnut]]
|
||||
- [[doom-package:][synosaurus]]
|
||||
|
||||
** Hacks
|
||||
/No hacks documented for this module./
|
||||
|
||||
** TODO Changelog
|
||||
# This section will be machine generated. Don't edit it by hand.
|
||||
/This module does not have a changelog yet./
|
||||
|
||||
* Installation
|
||||
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
||||
|
||||
This module has several optional dependencies:
|
||||
|
||||
- ~ripgrep~ as a last-resort fallback for jump-to-definition/find-references.
|
||||
- ~sqlite3~ for Dash docset support (if you have [[doom-module:][+docsets]] enabled)
|
||||
- ~wordnet~ for offline dictionary and thesaurus support (if you have
|
||||
[[doom-module:][+dictionary]] and [[doom-module:][+offline]] enabled).
|
||||
|
||||
** MacOS
|
||||
#+BEGIN_SRC sh
|
||||
#+begin_src sh
|
||||
brew install ripgrep wordnet
|
||||
|
||||
# An older version of sqlite is included in MacOS. If it causes you problems (and
|
||||
|
|
@ -77,27 +75,27 @@ 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
|
||||
#+end_src
|
||||
|
||||
** Arch Linux
|
||||
#+BEGIN_SRC sh
|
||||
#+begin_src sh
|
||||
sudo pacman -S sqlite ripgrep
|
||||
yay -S wordnet-cli
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
** NixOS
|
||||
#+BEGIN_SRC nix
|
||||
#+begin_src nix
|
||||
environment.systemPackages = with pkgs; [
|
||||
ripgrep
|
||||
sqlite
|
||||
wordnet
|
||||
];
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
* Features
|
||||
* Usage
|
||||
** Jump to definition
|
||||
Use ~+lookup/definition~ (bound to =gd= in normal mode) to jump to the
|
||||
definition of the symbol at point
|
||||
Use ~+lookup/definition~ (bound to [[kbd:][gd]] in normal mode) to jump to the definition
|
||||
of the symbol at point.
|
||||
|
||||
This module provides a goto-definition implementation that will try the
|
||||
following sources before giving up:
|
||||
|
|
@ -105,30 +103,30 @@ following sources before giving up:
|
|||
1. Whatever ~:definition~ function is registered for the current buffer with the
|
||||
~:lookup~ setting (see "Configuration" section).
|
||||
2. Any available xref backends.
|
||||
3. ~dumb-jump~ (a text search with aides to reduce false positives).
|
||||
3. An ordinary project-wide text search with ripgrep.
|
||||
3. [[doom-package:][dumb-jump]] (a text search with aides to reduce false positives).
|
||||
3. An ordinary project-wide text search with =ripgrep=.
|
||||
5. If ~evil-mode~ is active, use ~evil-goto-definition~, which preforms a simple
|
||||
text search within the current buffer.
|
||||
|
||||
If there are multiple results, you will be prompted to select one.
|
||||
|
||||
** Find references
|
||||
Use ~+lookup/references~ (bound to =gD= in normal mode) to see a list of
|
||||
Use ~+lookup/references~ (bound to [[kbd:][gD]] in normal mode) to see a list of
|
||||
references for the symbol at point from throughout your project.
|
||||
|
||||
Like ~+lookup/definition~, this tries a number of sources before giving up. It
|
||||
will try:
|
||||
|
||||
1. Whatever ~:references~ function is registered for the current buffer with the
|
||||
~:lookup~ setting (see "Configuration" section).
|
||||
2. Any available xref backends.
|
||||
~:lookup~ setting (see [[*Configuration][Configuration]]).
|
||||
2. Any available [[doom-package:][xref]] backends.
|
||||
3. An ordinary project-wide text search with ripgrep.
|
||||
|
||||
If there are multiple results, you will be prompted to select one.
|
||||
|
||||
** Look up documentation
|
||||
~+lookup/documentation~ (bound to =K= in normal mode) will open documentation
|
||||
for the symbol at point.
|
||||
~+lookup/documentation~ (bound to [[kbd:][K]] in normal mode) will open documentation for
|
||||
the symbol at point.
|
||||
|
||||
Depending on your configuration, this will try a list of sources:
|
||||
|
||||
|
|
@ -143,36 +141,41 @@ 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.
|
||||
+ Online (generic): ~+lookup/online~ or ~+lookup/online-select~ (bound to =SPC /
|
||||
o=), or ~:lo[okup] QUERY~ for evil users.
|
||||
+ Online (generic): ~+lookup/online~ or ~+lookup/online-select~ (bound to [[kbd:][SPC /
|
||||
o]]), or ~:lo[okup] QUERY~ for evil users.
|
||||
|
||||
** Dash.app Docset integration
|
||||
You can install dash docsets with ~M-x dash-docset-install-docset~ and search
|
||||
You can install dash docsets with ~M-x dash-docs-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.
|
||||
|
||||
* Configuration
|
||||
** Associating lookup handlers with major modes
|
||||
~set-lookup-handlers! MODES &key DEFINITION REFERENCES DOCUMENTATION FILE XREF-BACKEND ASYNC~
|
||||
~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~.
|
||||
+ ~:references FN~ :: Run when looking for usage references of a symbol in the
|
||||
current project. Used by ~+lookup/references~.
|
||||
+ ~:documentation FN~ :: Run when looking up documentation for a symbol. Used by
|
||||
~+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, which implicitly provides
|
||||
:definition and :references handlers. If you specify them anyway, they will
|
||||
take precedence over the xref backend, however.
|
||||
- ~:definition FN~ ::
|
||||
Run when jumping to a symbol's definition. Used by ~+lookup/definition~.
|
||||
- ~:references FN~ ::
|
||||
Run when looking for usage references of a symbol in the current project. Used
|
||||
by ~+lookup/references~.
|
||||
- ~:documentation FN~ ::
|
||||
Run when looking up documentation for a symbol. Used by
|
||||
~+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 [[doom-package:][xref]] backend, which implicitly provides ~:definition~ and
|
||||
~:references~ handlers. If you specify them anyway, they will take precedence
|
||||
over the xref backend, however.
|
||||
|
||||
e.g.
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
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:
|
||||
(set-lookup-handlers! 'python-mode
|
||||
|
|
@ -185,7 +188,7 @@ e.g.
|
|||
;; experience. You can specify custom xref backends with:
|
||||
(set-lookup-handlers! 'js2-mode :xref-backend #'xref-js2-xref-backend)
|
||||
;; NOTE: xref doesn't provide a :documentation backend.
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
** Associating Dash docsets with major modes
|
||||
~set-docsets! MODES &rest DOCSETS...~
|
||||
|
|
@ -194,31 +197,30 @@ 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
|
||||
E.g.
|
||||
#+begin_src emacs-lisp
|
||||
(set-docsets! 'js2-mode "JavaScript" "JQuery")
|
||||
;; Add docsets to minor modes by starting DOCSETS with :add
|
||||
(set-docsets! 'rjsx-mode :add "React")
|
||||
;; Or remove docsets from minor modes
|
||||
(set-docsets! 'nodejs-mode :remove "JQuery")
|
||||
#+END_SRC
|
||||
#+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 ~dash-docset-install-docset~.
|
||||
docsets must be installed with ~dash-docs-install-docset~.
|
||||
|
||||
** Open in eww instead of browser
|
||||
~+lookup/online~ opens the search results with in ~+lookup-open-url-fn~
|
||||
(default: ~#'browse-url~). Here is how to change this to EWW (so it opens inside
|
||||
Emacs):
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
#+begin_src emacs-lisp
|
||||
(setq +lookup-open-url-fn #'eww)
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
#+begin_quote
|
||||
~+lookup/in-docsets~ consults ~dash-docs-browser-func~ instead, which is already
|
||||
set to ~#'eww~ by default.
|
||||
📌 ~+lookup/in-docsets~ consults ~dash-docs-browser-func~ instead, which is
|
||||
already set to ~#'eww~ by default.
|
||||
#+end_quote
|
||||
|
||||
** Open in Xwidget WebKit instead of browser
|
||||
|
|
@ -226,19 +228,28 @@ To open results from ~+lookup/online~ or ~+lookup/in-docsets~ in Xwidget WebKit
|
|||
instead of your system browser, set ~+lookup-open-url-fn~ and/or
|
||||
~dash-docs-browser-func~ to ~+lookup-xwidget-webkit-open-url-fn~ (needs Emacs
|
||||
with Xwidgets support):
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
#+begin_src emacs-lisp
|
||||
(setq +lookup-open-url-fn #'+lookup-xwidget-webkit-open-url-fn)
|
||||
(after! dash-docs
|
||||
(setq dash-docs-browser-func #'+lookup-xwidget-webkit-open-url-fn))
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
* Troubleshooting
|
||||
/There are no known problems with this module./ [[doom-report:][Report one?]]
|
||||
|
||||
* Frequently asked questions
|
||||
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
||||
|
||||
* TODO Appendix
|
||||
#+begin_quote
|
||||
🔨 /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
|
||||
#+end_quote
|
||||
|
||||
* Appendix
|
||||
** Commands
|
||||
+ ~+lookup/definition~
|
||||
+ ~+lookup/references~
|
||||
+ ~+lookup/documentation~
|
||||
+ ~+lookup/online~
|
||||
+ ~+lookup/online-select~
|
||||
+ ~+lookup/in-devdocs~
|
||||
+ ~+lookup/in-docsets~
|
||||
- ~+lookup/definition~
|
||||
- ~+lookup/references~
|
||||
- ~+lookup/documentation~
|
||||
- ~+lookup/online~
|
||||
- ~+lookup/online-select~
|
||||
- ~+lookup/in-devdocs~
|
||||
- ~+lookup/in-docsets~
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue