Skip to content

Latest commit

 

History

History
74 lines (61 loc) · 3.36 KB

20230226.org

File metadata and controls

74 lines (61 loc) · 3.36 KB
Raw

Using dash-docs from Spacemacs

Spacemacs has a Dash layer but it doesn’t seem to add much to the functionality the dash-docs packages provides out of the box. So instead of using that layer, I’m using these packages directly and this note describes how.

Installation

To install a third-party package like helm-dash in Spacemacs, you add it to variable dotspacemacs-additional-packages. helm-dash requires dash-docs so when Spacemacs installs helm-dash, it will download dash-docs from Melpa unless it’s already installed. However, I want Spacemacs to use my custom version of dash-docs, so I need to specify that too:

dotspacemacs-additional-packages
`(
  (dash-docs :location (recipe :fetcher github :repo "swinkels/dash-docs" :branch "avoid-cannot-open-message"))
  helm-dash
  )

Unfortunately, even with the snippet above, Spacemacs installs both helm-dash and dash-docs from Melpa. The workaround is to manually delete the installed dash-docs package[fn:1] and to restart Emacs. On restart, Spacemacs will detect dash-docs is missing and install it again, this time from the location specified in dotspacemacs-additional-packages.

Customization

The following snippet lazy loads helm-dash and binds the two main functions:

(use-package helm-dash
  ;; don't load the package until you explicitly trigger its load, for example,
  ;; when you call one of the autoloaded functions
  :defer t
  :init
  ;; bind the following helm-dash functions before the package is loaded - note
  ;; that these two functions are autoloaded
  (spacemacs/set-leader-keys-for-major-mode 'python-mode "hd" 'helm-dash-at-point)
  (spacemacs/set-leader-keys-for-major-mode 'python-mode "hD" 'helm-dash))

Spacemacs also binds , h d to helm-pydoc so we lose that binding. I don’t use helm-pydoc, so I can live with that.

Finally, use the following hook to automatically activate documentation set “Python 3” when using Python:

(defun configure-dash-docs-for-python()
  (setq-local dash-docs-common-docsets '("Python 3")))

(add-hook 'python-mode-hook 'configure-dash-docs-for-python)

The official dash-docs documentation states you should use set dash-docs-docsets, but that’s an error.

Removal of pylookup

pylookup is an older Emacs package that also allows you to build and query a local database of HTML documentation. It’s part of the Python layer[fn:2] but as its functionality is covered by dash-docs, I removed it from my Spacemacs installation:

dotspacemacs-excluded-packages '(pylookup)

This automatically removes its key binding , h h, to pylookup-lookup.

Footnotes

[fn:1] By default Spacemacs installs packages in $HOME/.emacs/elpa/<emacs-major>.<emacs-minor>/develop.

[fn:2] The upstream version of pylookup is not Python3-compatible. A Python3-compatible version has been merged into the Spacemacs Python layer as local/pylookup.