telescope-docsets.nvim

Query and view docsets using Telescope in Neovim.

Installation

This plugin requires telescope.nvim and plenary.nvim!

Additionally, it requires dasht.

If you want to preview docsets in Telescope, you must have elinks installed as well. NOTE: I have found that elinks does not work great when rendering documentation html :(

Setup and configuration

require("telescope").load_extension("docsets")

There are currently three points of customization:

1. The program used to query docsets
2. The program used to open docpages
3. The program used to preview docpages

require("telescope").setup {
  ...
  extensions = {
    docsets = {
      query_command = <function or string>,
      open_command = <function or string>,
      preview_command = <function>,
    }
  }
}

query_command can be either a function or a string. If it is a function, it will be passed a single argument, opts, which are the options passed by telescope to the telescope-docsets extensions at runtime and return a string which is an executable command/program found in $PATH. If it is a string, it should be an executable command/program found in $PATH.

The default query_command is "dasht-query-line".

Similarly, open_command can be either a function or a string. If it is a function, it will be passed a single argument, entry, which is a telescope entry of the form:

{
  name = <string>,
  type = <string>,
  from = <string>,
  url = <string>,
}

The function should open the docpage (asynchronously!) (e.g. in a browser), whatever that means. The default open_command is:

function(entry)
  Job:new({ command = vim.env.BROWSER, args = { entry.value.url }, detached = true }):start()
end

preview_command must be a function that accepts a single argument, entry. It must return a table representing the commandline (including arguments) to use to execute the "preview".

The default preview_command is:

function(entry)
  return { "elinks", "-dump", entry.value.url }
end

Usage

From lua:

require("telescope").extensions.docsets.find_word_under_cursor()

From the command prompt:

:Telescope docsets find_word_under_cursor

Features

• Query documentation using dasht for the word under the cursor
• <CR> opens the selected docpage in your $BROWSER
• Use elinks to preview selected docpage
• Configuration
  • dasht executable path
  • vim.env.BROWSER
  • elinks commandline
• Look into alternatives for elinks
• Map filetype (or syntax) to docsets?
• Specify the docset in the query (in dasht you can do: dasht cpp std::string to filter the search)
• Dynamic search (no query, not sure how to do this with dasht?)