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

#+html: <p align="center">
#+html: <a href="http://elpa.gnu.org/packages/devdocs.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/devdocs.svg"/></a>
#+html: <a href="https://melpa.org/#/devdocs"><img alt="MELPA" src="https://melpa.org/packages/devdocs-badge.svg"/></a>
#+html: </p>

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=.

#+html: <img alt="Reading and looking up documentation entries" src="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.

** Customization

Run =M-x customize-group RET devdocs RET= to see a listing of
customization options.

You can enable rendering of mathematical formulas by installing the
[[https://elpa.gnu.org/packages/mathjax.html][mathjax]] package.  Note that this additionally requires having [[https://nodejs.org/][Node.js]]
installed on your machine.

** 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.