devdocs.el

devdocs.el copied to clipboard

#+title: devdocs.el --- Emacs viewer for DevDocs

#+html: #+html:

devdocs.el is a documentation viewer for Emacs similar to the built-in Info browser, but geared towards documentation distributed by the [[https://devdocs.io][DevDocs]] website. Currently, this covers over 500 versions of 188 different software components.

The stable version of the package is available from [[https://elpa.gnu.org/packages/devdocs.html][GNU ELPA]] and a development version is available from [[https://melpa.org/#/devdocs][MELPA]]; to install, type =M-x package-install RET devdocs=.

#+caption: Reading and looking up documentation entries. [[https://raw.githubusercontent.com/astoff/devdocs.el/images/screenshot.png]]

** Basic usage

To get started, download some documentation with =M-x devdocs-install=. This will query https://devdocs.io for the available documents and save the selected one to disk. To read the installed documentation, there are two options:

• =devdocs-peruse=: Select a document and display its first page.
• =devdocs-lookup=: Select an index entry and display it.

It's handy to have a keybinding for the latter command. One possibility, in analogy to =C-h S= (=info-lookup-symbol=), is

#+begin_src elisp (global-set-key (kbd "C-h D") 'devdocs-lookup) #+end_src

In any given buffer, the first call to =devdocs-lookup= will query for a list of documents to search (you can select more than one option by entering a comma-separated list). This selection will be remembered in subsequent calls to =devdocs-lookup=, unless a prefix argument is given; in this case you can select a new list of documents.

In the =devdocs= buffer, navigation keys similar to Info and =Help= buffers are available; press =C-h m= for details. Internal hyperlinks are opened in the same viewing buffer, and external links are opened as =browse-url= normally would.

** Managing documents

To manage the collection of installed documents, use the following commands:

• =devdocs-install=: Download and install (or reinstall) a document distributed by [[https://devdocs.io]].
• =devdocs-delete=: Remove an installed document.
• =devdocs-update-all=: Download and reinstall all installed documents for which a newer version is available.

In some cases, variants of a document are available for each (major) version. It is possible to install several versions in parallel.

Documents are installed under =devdocs-data-dir=, which defaults to =~/.emacs.d/devdocs=. To completely uninstall the package, remove this directory.

** Setting the default documents for a collection of buffers

You may wish to select a predefined list of documents in all buffers of a certain major mode or project. To achieve this, set the =devdocs-current-docs= variable directly, say via [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html][dir-local variables]] or a mode hook:

#+begin_src elisp (add-hook 'python-mode-hook (lambda () (setq-local devdocs-current-docs '("python~3.9")))) #+end_src

As usual, calling =devdocs-lookup= with a prefix argument redefines the selected documents for that specific buffer.

** Contributing

Discussions, suggestions and code contributions are welcome! Since this package is part of GNU ELPA, nontrivial contributions (above 15 lines of code) require a copyright assignment to the FSF.