change!: build the docs at download time & add picker previewer

Docs are now converted to markdown and splited into multiple files at download time, installation and uninstall behavior also changed so old docs and index.json are now incompatible with the plugin. The picker now also support preview for global search.

Author: luckasRanarison

README.md

@@ -60,27 +60,25 @@ Here is the default configuration:
 {
   dir_path = vim.fn.stdpath("data") .. "/devdocs", -- installation directory
   telescope = {}, -- passed to the telescope picker
-  telescope_alt = { -- when searching globally without preview
-    layout_config = {
-      width = 75,
-    },
-  },
   float_win = { -- passed to nvim_open_win(), see :h api-floatwin
     relative = "editor",
     height = 25,
     width = 100,
     border = "rounded",
   },
-  previewer_cmd = nil, -- like glow
-  cmd_args = {}, -- example using glow { "-s", "dark", "-w", "80" }
   wrap = false, -- text wrap, only applies to floating window
+  previewer_cmd = nil, -- for example: "glow"
+  cmd_args = {}, -- example using glow: { "-s", "dark", "-w", "80" }
+  cmd_ignore = {}, -- ignore cmd rendering for the listed docs
+  picker_cmd = false, -- use cmd previewer in picker preview
+  picker_cmd_args = {}, -- example using glow: { "-p" }
   ensure_installed = {}, -- get automatically installed
 }
 ```
 
 ## Usage
 
-To use the documentations from nvim-devdocs you have to **install** the documentation using `:DevdocsInstall`.
+To use the documentations from nvim-devdocs, you need to install it by executing `:DevdocsInstall`. The documentation is indexed and built during the download. Since the building process is done synchronously and may block input, you may want to download larger documents (more than 10MB) in headless mode: `nvim --headless +"DevdocsInstall rust"`.
 
 ## Commands
 
@@ -98,10 +96,6 @@ Available commands:
 
 Commands support completion, and the Telescope picker will be used when no argument is provided.
 
-> ℹ️ **NOTE**:<br>
-> At the moment, Telescope's Previewer is available only when opening a specific documentation.
-> E.g. `:DevdocsOpen javascript`
-
 ## TODO
 
 - More search options

lua/nvim-devdocs/build.lua

@@ -0,0 +1,69 @@
+local path = require("plenary.path")
+
+local notify = require("nvim-devdocs.notify")
+local plugin_config = require("nvim-devdocs.config").get()
+local html_to_md = require("nvim-devdocs.transpiler").html_to_md
+
+local function build_docs(entry, index, docs)
+  local alias = entry.slug:gsub("~", "-")
+
+  notify.log("Building " .. alias .. " documentation...")
+
+  local docs_dir = path:new(plugin_config.dir_path, "docs")
+  local current_doc_dir = path:new(docs_dir, alias)
+  local index_path = path:new(plugin_config.dir_path, "index.json")
+  local lock_path = path:new(plugin_config.dir_path, "docs-lock.json")
+
+  if not docs_dir:exists() then docs_dir:mkdir() end
+  if not current_doc_dir:exists() then current_doc_dir:mkdir() end
+  if not index_path:exists() then index_path:write("{}", "w") end
+  if not lock_path:exists() then lock_path:write("{}", "w") end
+
+  local section_map = {}
+  local path_map = {}
+
+  for _, index_entry in pairs(index.entries) do
+    local splited = vim.split(index_entry.path, "#")
+    local main = splited[1]
+    local id = splited[2]
+
+    if not section_map[main] then section_map[main] = {} end
+    if id then table.insert(section_map[main], id) end
+  end
+
+  local count = 1
+
+  for key, doc in pairs(docs) do
+    local sections = section_map[key]
+
+    local markdown, md_sections = html_to_md(doc, sections)
+
+    for id, md_path in pairs(md_sections) do
+      path_map[key .. "#" .. id] = count .. "," .. md_path
+    end
+
+    path_map[key] = tostring(count)
+
+    local file_path = path:new(current_doc_dir, tostring(count) .. ".md")
+
+    file_path:write(markdown, "w")
+    count = count + 1
+  end
+
+  for i, index_entry in ipairs(index.entries) do
+    local main = vim.split(index_entry.path, "#")[1]
+    index.entries[i].path = path_map[index_entry.path] or path_map[main]
+  end
+
+  local index_parsed = vim.fn.json_decode(index_path:read())
+  index_parsed[alias] = index
+  index_path:write(vim.fn.json_encode(index_parsed), "w")
+
+  local lock_parsed = vim.fn.json_decode(lock_path:read())
+  lock_parsed[alias] = entry
+  lock_path:write(vim.fn.json_encode(lock_parsed), "w")
+
+  notify.log("Build complete!")
+end
+
+return build_docs

lua/nvim-devdocs/config.lua

@@ -3,20 +3,18 @@ local M = {}
 local config = {
   dir_path = vim.fn.stdpath("data") .. "/devdocs",
   telescope = {},
-  telescope_alt = {
-    layout_config = {
-      width = 75,
-    },
-  },
   float_win = {
     relative = "editor",
     height = 25,
     width = 100,
     border = "rounded",
   },
+  wrap = false,
   previewer_cmd = nil,
   cmd_args = {},
-  wrap = false,
+  cmd_ignore = {},
+  picker_cmd = false,
+  picker_cmd_args = {},
   ensure_installed = {},
 }
 

lua/nvim-devdocs/list.lua

@@ -1,25 +1,19 @@
 local M = {}
 
 local path = require("plenary.path")
-local scandir = require("plenary.scandir")
 
 local notify = require("nvim-devdocs.notify")
 local plugin_config = require("nvim-devdocs.config").get()
 
-local docs_dir = path:new(plugin_config.dir_path, "docs")
-local index_path = path:new(plugin_config.dir_path, "index.json")
+local lock_path = path:new(plugin_config.dir_path, "docs-lock.json")
 local registery_path = path:new(plugin_config.dir_path, "registery.json")
 
 M.get_installed_alias = function()
-  if not docs_dir:exists() then return {} end
+  if not lock_path:exists() then return {} end
 
-  local files = scandir.scan_dir(path.__tostring(docs_dir), { all_dirs = false })
-  local installed = vim.tbl_map(function(file_path)
-    local splited = path._split(path:new(file_path))
-    local filename = splited[#splited]
-    local basename = filename:gsub(".json", "")
-    return basename
-  end, files)
+  local lockfile = lock_path:read()
+  local lock_parsed = vim.fn.json_decode(lockfile)
+  local installed = vim.tbl_keys(lock_parsed)
 
   return installed
 end
@@ -45,20 +39,20 @@ M.get_installed_entry = function()
 end
 
 M.get_updatable = function()
-  if not registery_path:exists() then return {} end
-  if not index_path:exists() then return {} end
+  if not registery_path:exists() or not lock_path:exists() then return {} end
 
   local results = {}
-  local registery_content = registery_path:read()
-  local registery_parsed = vim.fn.json_decode(registery_content)
-  local index_content = index_path:read()
-  local index_parsed = vim.fn.json_decode(index_content)
-
-  for alias, value in pairs(index_parsed) do
-    local slug = alias:gsub("-", "~")
+  local registery = registery_path:read()
+  local registery_parsed = vim.fn.json_decode(registery)
+  local lockfile = lock_path:read()
+  local lock_parsed = vim.fn.json_decode(lockfile)
 
+  for alias, value in pairs(lock_parsed) do
     for _, doc in pairs(registery_parsed) do
-      if doc.slug == slug and doc.mtime > value.mtime then table.insert(results, alias) end
+      if doc.slug == value.slug and doc.mtime > value.mtime then
+        table.insert(results, alias)
+        break
+      end
     end
   end