docs: refactor generation

- rename scripts dir to docgen - slightly change placeholder syntax - move duplicate static docs into separate files
saecki · Dec 4, 2023 · d0bb911 · d0bb911
1 parent 343bea7
commit d0bb911
Show file tree

Hide file tree

Showing 17 changed files with 385 additions and 430 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -23,14 +23,13 @@ make build
 ```
 
 ## Documentation
-__Do not edit the `README.md` or `doc/crates.txt` files.__
+__Do not edit the `README.md`, `doc/crates.txt` or wiki files.__
 
-To update the README or vimdoc edit the `scripts/README.md.in` and
-`scripts/crates.txt.in` files instead of their generated counter parts.
+To update the README, vimdoc or wiki edit the files in `docgen/templates/*`
+instead of their generated counter parts.
 
-After editing one of the above, the configuration schema in
-`lua/crates/config.tl` or public api functions in `lua/crates.tl` update the
-docs by running this command:
+Documentation is automatically updated by github actions, but you can also
+generate it yourself by running:
 ```
 make doc
 ```

diff --git a/Makefile b/Makefile
@@ -8,5 +8,5 @@ test:
 
 .PHONY: doc
 doc:
-	./scripts/gen_doc.lua
+	./docgen/gen_doc.lua
 
diff --git a/doc/crates.txt b/doc/crates.txt
@@ -252,16 +252,16 @@ For more information about the lua function see |crates-functions|.
     vim.keymap.set('n', '<leader>cf', crates.show_features_popup, opts)
     vim.keymap.set('n', '<leader>cd', crates.show_dependencies_popup, opts)
 
-    vim.keymap.set('n', '<leader>ce', crates.expand_plain_crate_to_inline_table, opts)
-    vim.keymap.set('n', '<leader>cE', crates.extract_crate_into_table, opts)
-
     vim.keymap.set('n', '<leader>cu', crates.update_crate, opts)
     vim.keymap.set('v', '<leader>cu', crates.update_crates, opts)
     vim.keymap.set('n', '<leader>ca', crates.update_all_crates, opts)
     vim.keymap.set('n', '<leader>cU', crates.upgrade_crate, opts)
     vim.keymap.set('v', '<leader>cU', crates.upgrade_crates, opts)
     vim.keymap.set('n', '<leader>cA', crates.upgrade_all_crates, opts)
 
+    vim.keymap.set('n', '<leader>ce', crates.expand_plain_crate_to_inline_table, opts)
+    vim.keymap.set('n', '<leader>cE', crates.extract_crate_into_table, opts)
+
     vim.keymap.set('n', '<leader>cH', crates.open_homepage, opts)
     vim.keymap.set('n', '<leader>cR', crates.open_repository, opts)
     vim.keymap.set('n', '<leader>cD', crates.open_documentation, opts)
@@ -277,16 +277,16 @@ And here are the same ones in vimscript.
     nnoremap <silent> <leader>cf :lua require('crates').show_features_popup()<cr>
     nnoremap <silent> <leader>cd :lua require('crates').show_dependencies_popup()<cr>
 
-    nnoremap <silent> <leader>ce :lua require('crates').expand_plain_crate_to_inline_table()<cr>
-    nnoremap <silent> <leader>cE :lua require('crates').extract_crate_into_table()<cr>
-
     nnoremap <silent> <leader>cu :lua require('crates').update_crate()<cr>
     vnoremap <silent> <leader>cu :lua require('crates').update_crates()<cr>
     nnoremap <silent> <leader>ca :lua require('crates').update_all_crates()<cr>
     nnoremap <silent> <leader>cU :lua require('crates').upgrade_crate()<cr>
     vnoremap <silent> <leader>cU :lua require('crates').upgrade_crates()<cr>
     nnoremap <silent> <leader>cA :lua require('crates').upgrade_all_crates()<cr>
 
+    nnoremap <silent> <leader>ce :lua require('crates').expand_plain_crate_to_inline_table()<cr>
+    nnoremap <silent> <leader>cE :lua require('crates').extract_crate_into_table()<cr>
+
     nnoremap <silent> <leader>cH :lua require('crates').open_homepage()<cr>
     nnoremap <silent> <leader>cR :lua require('crates').open_repository()<cr>
     nnoremap <silent> <leader>cD :lua require('crates').open_documentation()<cr>

diff --git a/scripts/gen_doc.lua → docgen/gen_doc.lua b/scripts/gen_doc.lua → docgen/gen_doc.lua
@@ -8,6 +8,15 @@ local config = require('lua.crates.config')
 local highlight = require('lua.crates.highlight')
 local version = "unstable"
 
+local function gen_from_shared_file(lines, indent, filename)
+    local infile = io.open("docgen/shared/" .. filename, "r")
+    for l in infile:lines("*l") do
+        l = string.rep("    ", indent) .. l
+        l = l:gsub("%s+$", "")
+        table.insert(lines, l)
+    end
+end
+
 local function format_markdown_refs(line)
     line = line:gsub("`f#([^`]+)`", "`%1`")
     line = line:gsub("`p#([^`]+)`", "`%1`")
@@ -224,14 +233,6 @@ local function gen_vimdoc_config(lines, path, schema)
     end
 end
 
-local function gen_plain_text_config(lines, indent)
-    local infile = io.open("scripts/plain_text_config.lua", "r")
-    for l in infile:lines("*l") do
-        local indented = string.rep("    ", indent) .. l
-        table.insert(lines, indented)
-    end
-end
-
 local function gen_def_config(lines, indent, path, schema)
     local function insert_indent(str)
         local l = string.rep("    ", #path + indent) .. str
@@ -255,25 +256,41 @@ local function gen_def_config(lines, indent, path, schema)
     end
 end
 
+local function parse_placeholder(l)
+    local preceeding_spaces, placeholder = l:match("^%s*()<SHARED%:([a-zA-Z0-9_%.]+)>$")
+    if placeholder then
+        local spaces = preceeding_spaces - 1
+        if spaces % 4 ~= 0 then
+            error(string.format("4 space indent is enforced, but found %s spaced in line:\n%s", spaces, l))
+        end
+        local indent = spaces / 4
+        return placeholder, indent
+    end
+end
+
 local function gen_vim_doc()
     local lines = {}
 
-    local infile = io.open("scripts/crates.txt.in", "r")
+    local infile = io.open("docgen/templates/crates.txt.in", "r")
     for l in infile:lines("*l") do
-        if l == "<DEFAULT_CONFIGURATION>" then
-            gen_def_config(lines, 2, {}, config.schema)
-        elseif l == "<PLAIN_TEXT_CONFIGURATION>" then
-            gen_plain_text_config(lines, 2)
-        elseif l == "<FUNCTIONS>" then
-            gen_vimdoc_functions(lines)
-        elseif l == "<CONFIGURATION>" then
-            gen_vimdoc_config(lines, {}, config.schema)
-        elseif l == "<HIGHLIGHTS>" then
-            gen_vimdoc_highlights(lines)
+        local ph, indent = parse_placeholder(l)
+        if ph then
+            if ph == "DEFAULT_CONFIGURATION" then
+                gen_def_config(lines, 2, {}, config.schema)
+            elseif ph == "FUNCTIONS" then
+                gen_vimdoc_functions(lines)
+            elseif ph == "CONFIGURATION" then
+                gen_vimdoc_config(lines, {}, config.schema)
+            elseif ph == "HIGHLIGHTS" then
+                gen_vimdoc_highlights(lines)
+            else
+                gen_from_shared_file(lines, indent, ph)
+            end
         else
             l = l:gsub("<VERSION>", version)
             table.insert(lines, l)
         end
+
     end
     infile:close()
 
@@ -283,20 +300,22 @@ local function gen_vim_doc()
     outfile:close()
 end
 
-local function gen_markdown(inpath, outpath, title)
+local function gen_markdown(inpath, outpath)
     local lines = {}
 
     local infile = io.open(inpath, "r")
     for l in infile:lines("*l") do
-        if l == "<DEFAULT_CONFIGURATION>" then
-            gen_def_config(lines, 1, {}, config.schema)
-        elseif l == "<PLAIN_TEXT_CONFIGURATION>" then
-            gen_plain_text_config(lines, 1)
-        elseif l == "<FUNCTIONS>" then
-            gen_markdown_functions(lines)
+        local ph, indent = parse_placeholder(l)
+        if ph then
+            if ph == "DEFAULT_CONFIGURATION" then
+                gen_def_config(lines, 1, {}, config.schema)
+            elseif ph == "FUNCTIONS" then
+                gen_markdown_functions(lines)
+            else
+                gen_from_shared_file(lines, indent, ph)
+            end
         else
             l = l:gsub("<VERSION>", version)
-            l = l:gsub("<TITLE>", title)
             table.insert(lines, l)
         end
     end
@@ -310,8 +329,8 @@ end
 
 local function gen_docs()
     gen_vim_doc()
-    gen_markdown("scripts/README.md.in", "README.md", "")
-    gen_markdown("scripts/documentation.md.in", "scripts/wiki/Unstable-documentation.md", "Unstable documentation")
+    gen_markdown("docgen/templates/README.md.in", "README.md")
+    gen_markdown("docgen/templates/documentation.md.in", "docgen/wiki/Unstable-documentation.md")
 end
 
 gen_docs()
diff --git a/docgen/shared/keymaps.lua b/docgen/shared/keymaps.lua
@@ -0,0 +1,24 @@
+local crates = require('crates')
+local opts = { silent = true }
+
+vim.keymap.set('n', '<leader>ct', crates.toggle, opts)
+vim.keymap.set('n', '<leader>cr', crates.reload, opts)
+
+vim.keymap.set('n', '<leader>cv', crates.show_versions_popup, opts)
+vim.keymap.set('n', '<leader>cf', crates.show_features_popup, opts)
+vim.keymap.set('n', '<leader>cd', crates.show_dependencies_popup, opts)
+
+vim.keymap.set('n', '<leader>cu', crates.update_crate, opts)
+vim.keymap.set('v', '<leader>cu', crates.update_crates, opts)
+vim.keymap.set('n', '<leader>ca', crates.update_all_crates, opts)
+vim.keymap.set('n', '<leader>cU', crates.upgrade_crate, opts)
+vim.keymap.set('v', '<leader>cU', crates.upgrade_crates, opts)
+vim.keymap.set('n', '<leader>cA', crates.upgrade_all_crates, opts)
+
+vim.keymap.set('n', '<leader>ce', crates.expand_plain_crate_to_inline_table, opts)
+vim.keymap.set('n', '<leader>cE', crates.extract_crate_into_table, opts)
+
+vim.keymap.set('n', '<leader>cH', crates.open_homepage, opts)
+vim.keymap.set('n', '<leader>cR', crates.open_repository, opts)
+vim.keymap.set('n', '<leader>cD', crates.open_documentation, opts)
+vim.keymap.set('n', '<leader>cC', crates.open_crates_io, opts)
diff --git a/docgen/shared/keymaps.vim b/docgen/shared/keymaps.vim
@@ -0,0 +1,21 @@
+nnoremap <silent> <leader>ct :lua require('crates').toggle()<cr>
+nnoremap <silent> <leader>cr :lua require('crates').reload()<cr>
+
+nnoremap <silent> <leader>cv :lua require('crates').show_versions_popup()<cr>
+nnoremap <silent> <leader>cf :lua require('crates').show_features_popup()<cr>
+nnoremap <silent> <leader>cd :lua require('crates').show_dependencies_popup()<cr>
+
+nnoremap <silent> <leader>cu :lua require('crates').update_crate()<cr>
+vnoremap <silent> <leader>cu :lua require('crates').update_crates()<cr>
+nnoremap <silent> <leader>ca :lua require('crates').update_all_crates()<cr>
+nnoremap <silent> <leader>cU :lua require('crates').upgrade_crate()<cr>
+vnoremap <silent> <leader>cU :lua require('crates').upgrade_crates()<cr>
+nnoremap <silent> <leader>cA :lua require('crates').upgrade_all_crates()<cr>
+
+nnoremap <silent> <leader>ce :lua require('crates').expand_plain_crate_to_inline_table()<cr>
+nnoremap <silent> <leader>cE :lua require('crates').extract_crate_into_table()<cr>
+
+nnoremap <silent> <leader>cH :lua require('crates').open_homepage()<cr>
+nnoremap <silent> <leader>cR :lua require('crates').open_repository()<cr>
+nnoremap <silent> <leader>cD :lua require('crates').open_documentation()<cr>
+nnoremap <silent> <leader>cC :lua require('crates').open_crates_io()<cr>
diff --git a/scripts/plain_text_config.lua → docgen/shared/plain_text_config.lua b/scripts/plain_text_config.lua → docgen/shared/plain_text_config.lua
diff --git a/docgen/shared/show_docs.lua b/docgen/shared/show_docs.lua
@@ -0,0 +1,14 @@
+local function show_documentation()
+    local filetype = vim.bo.filetype
+    if vim.tbl_contains({ 'vim','help' }, filetype) then
+        vim.cmd('h '..vim.fn.expand('<cword>'))
+    elseif vim.tbl_contains({ 'man' }, filetype) then
+        vim.cmd('Man '..vim.fn.expand('<cword>'))
+    elseif vim.fn.expand('%:t') == 'Cargo.toml' and require('crates').popup_available() then
+        require('crates').show_popup()
+    else
+        vim.lsp.buf.hover()
+    end
+end
+
+vim.keymap.set('n', 'K', show_documentation, { silent = true })
diff --git a/docgen/shared/show_docs.vim b/docgen/shared/show_docs.vim
@@ -0,0 +1,12 @@
+nnoremap <silent> K :call <SID>show_documentation()<cr>
+function! s:show_documentation()
+    if (index(['vim','help'], &filetype) >= 0)
+        execute 'h '.expand('<cword>')
+    elseif (index(['man'], &filetype) >= 0)
+        execute 'Man '.expand('<cword>')
+    elseif (expand('%:t') == 'Cargo.toml' && luaeval('require("crates").popup_available()'))
+        lua require('crates').show_popup()
+    else
+        lua vim.lsp.buf.hover()
+    endif
+endfunction
diff --git a/scripts/README.md.in → docgen/templates/README.md.in b/scripts/README.md.in → docgen/templates/README.md.in
diff --git a/docgen/templates/crates.txt.in b/docgen/templates/crates.txt.in
@@ -0,0 +1,99 @@
+*crates.txt* Crates
+*crates.nvim*
+
+Author:   Tobias Schmitz <tobiasschmitz2001@gmail.com>
+Version:  <VERSION>
+Homepage: <https://github.com/saecki/crates.nvim>
+License:  MIT license
+
+==============================================================================
+INTRODUCTION                                                          *crates*
+
+Crates is a plugin that helps managing crates.io dependencies.
+It can display a crate's versions and features and allows you to update,
+upgrade, select, enable or disable them.
+
+==============================================================================
+USAGE                                                           *crates-usage*
+
+Basic setup.
+>
+    require('crates').setup()
+<
+
+Setup for plain text (without patched font).
+>
+    require('crates').setup {
+        <SHARED:plain_text_config.lua>
+    }
+<
+
+Setup with default options.
+Note the icons in the default config require a patched font, if you don't have
+one use the plain text config.
+For more information about individual config options see |crates-config|.
+>
+    require('crates').setup {
+        <SHARED:DEFAULT_CONFIGURATION>
+    }
+<
+
+==============================================================================
+MAPPINGS                                                     *crates-mappings*
+
+Note crates doesn't use any global key mappings by default.
+
+But here are some recommended ones.
+For more information about the lua function see |crates-functions|.
+>
+    <SHARED:keymaps.lua>
+<
+
+And here are the same ones in vimscript.
+>
+    <SHARED:keymaps.vim>
+<
+
+To integrate the crates popup in an idiomatic way into your configuration, you
+might want to use one of the following snippets for contextual documentation.
+
+How you might integrate `show_popup` into your `init.vim`.
+>
+    <SHARED:show_docs.vim>
+<
+
+How you might integrate `show_popup` into your `init.lua`.
+>
+    <SHARED:show_docs.lua>
+<
+
+==============================================================================
+FUNCTIONS                                                   *crates-functions*
+
+All of these functions are members of the `crates` root module.
+They can be accessed like this.
+>
+    require('crates').function_name()
+<
+
+<SHARED:FUNCTIONS>
+==============================================================================
+CONFIGURATION                                                  *crates-config*
+
+This section describes the configuration options which can be passed to
+`crates.setup()`. Note the type `section` indicates that the field
+is a table with subfields which will be extended with their default values, if
+not specified.
+
+<SHARED:CONFIGURATION>
+
+==============================================================================
+HIGHLIGHTS                                                 *crates-highlights*
+
+This is a list of the default highlight groups used by crates.nvim. To change
+them, you can either overwrite them or use different ones in
+|crates-config-highlight| and |crates-config-popup-highlight|.
+
+<SHARED:HIGHLIGHTS>
+
+vim:tw=78:ts=8:ft=help:norl: