docs: automatically generate help files from code
This takes the fennel code to generate documentation listing the shortcuts installed.
This commit is contained in:
Clément Joly
parent
2b68d91807
commit
8fd660aa7a
1
.gitignore
vendored
Normal file
1
.gitignore
vendored
Normal file
@ -0,0 +1 @@
|
||||
bepo-nvim-mapping
|
||||
21
Makefile
21
Makefile
@ -1,9 +1,11 @@
|
||||
fnl_files = $(wildcard fnl/*.fnl)
|
||||
out_files = $(fnl_files:fnl/%.fnl=lua/%.lua)
|
||||
help_file = help/bepo-nvim.txt
|
||||
help_file_mapping = bepo-nvim-mapping
|
||||
out_files = $(fnl_files:fnl/%.fnl=lua/%.lua) $(help_file) $(help_file_mapping)
|
||||
|
||||
all: $(out_files)
|
||||
|
||||
fmt: $(fnl_files)
|
||||
fmt: $(fnl_files) gen_doc.fnl
|
||||
fnlfmt --fix $<
|
||||
|
||||
lua/%.lua: fnl/%.fnl lua/
|
||||
@ -15,4 +17,17 @@ lua/:
|
||||
clean:
|
||||
rm -rf lua
|
||||
|
||||
.PHONY: clean compile
|
||||
doc: $(help_file)
|
||||
|
||||
$(help_file): $(help_file_mapping) help/
|
||||
rm $(help_file)
|
||||
cat $(help_file_mapping) >>$(help_file)
|
||||
rm $(help_file_mapping)
|
||||
|
||||
$(help_file_mapping): gen_doc.fnl $(fnl_files)
|
||||
fennel --raw-errors --no-compiler-sandbox --metadata --globals '*' gen_doc.fnl > $(help_file_mapping)
|
||||
|
||||
help/:
|
||||
mkdir -p help
|
||||
|
||||
.PHONY: clean doc $(help_file_mapping)
|
||||
|
||||
175
fnl/bepo.fnl
175
fnl/bepo.fnl
@ -36,104 +36,93 @@
|
||||
(map-normal key target)
|
||||
(map-text-object key target))
|
||||
|
||||
(fn mapping-movement []
|
||||
;; on préserve {hjkl} pour les directions
|
||||
(map-all :c :h)
|
||||
(map-all :t :j)
|
||||
(map-all :s :k)
|
||||
(map-all :r :l)
|
||||
(map-all :C :H)
|
||||
;; ------
|
||||
;; {JKL} devient [TSR]
|
||||
(map-all :T :J)
|
||||
(map-all :S :K)
|
||||
(map-all :R :L)
|
||||
;; ------
|
||||
;; on préserve les variantes avec 'g'
|
||||
(map-all :gt :gj)
|
||||
(map-all :gs :gk)
|
||||
;; ------
|
||||
;; on préserve les variantes avec 'z'
|
||||
(map-all :zT :zt)
|
||||
(map-all :zt :zj)
|
||||
(map-all :zk :zs)
|
||||
(map-all :zs :zk)
|
||||
;; ------
|
||||
;; {t} devient [h] pour être proche de [f]
|
||||
(map-all :h :t)
|
||||
;; idem pour {T} et [H]
|
||||
(map-all :H :T)
|
||||
;; {c} devient [l]
|
||||
(map-all :l :c)
|
||||
;; {C} devient [L]
|
||||
(map-all :L :C)
|
||||
;; {j} devient [r]
|
||||
(map-all :j :r)
|
||||
;; {J} devient [R]
|
||||
(map-all :J :R)
|
||||
;; {k} devient [s]
|
||||
(map-all :k :s)
|
||||
;; {K} devient [S]
|
||||
(map-all :K :S))
|
||||
(macro 𝛅 [...]
|
||||
"When called with the right context, this will print the documentation of the
|
||||
mappings, instead of attempting to bind. Since we access _G, this needs to be
|
||||
called with --no-compiler-sandbox (see
|
||||
https://fennel-lang.org/reference#compiler-environment)"
|
||||
(fn fun-to-mods [fun]
|
||||
"Converts a function to the modes it sets mappings for"
|
||||
(match (tostring fun)
|
||||
:map-text-object :ox
|
||||
:map-visual :v
|
||||
:map-normal :n
|
||||
:map-all :nx
|
||||
other (error (.. "Unsupported function " other))))
|
||||
|
||||
(fn mapping-tabs []
|
||||
;; le couple [gb]/[gé] agit sur les tabs
|
||||
(map-normal :gb :gT)
|
||||
(map-normal "gé" :gt)
|
||||
;; [gB] va au premier tab
|
||||
(map-normal :gB ":execute \"silent! tabfirst\"<CR>")
|
||||
;; [gÉ] au dernier
|
||||
(map-normal "gÉ" ":execute \"silent! tablast\"<CR>")
|
||||
;; [gT] est libéré et peut agir sur les tags
|
||||
(map-normal :gT "<C-]>"))
|
||||
(if _G.gen-doc
|
||||
(let [args [...]
|
||||
docstring (. args 3)
|
||||
(docstring body-pos) (if (= :string (type docstring))
|
||||
(values docstring 4)
|
||||
(values nil 3))
|
||||
body (-> args (unpack body-pos) (list)
|
||||
(#(icollect [_ v (pairs $1)]
|
||||
(match (type v)
|
||||
:string {:comment v}
|
||||
:table {:bepo (. v 2)
|
||||
:qwerty (. v 3)
|
||||
:modes (fun-to-mods (. v 1))}
|
||||
other (error (.. "Unsupported type" other))))))
|
||||
doc-struct {:fname (. args 1) : docstring : body}]
|
||||
`(local ,doc-struct.fname ,doc-struct))
|
||||
`(fn ,(unpack [...]))))
|
||||
|
||||
(fn mapping-easy-access []
|
||||
;; [<] est moins accessible que [«]
|
||||
(map-normal "«" "<")
|
||||
(map-visual "«" "<gv")
|
||||
;; idem pour [»] et [>]
|
||||
(map-normal "»" ">")
|
||||
(map-visual "»" ">gv")
|
||||
;; idem pour [g,] et [g;] qui sont permutés
|
||||
(map-all "g," "g;")
|
||||
(map-all "g;" "g,")
|
||||
;; [w] est peu accessible, on utilise [é]
|
||||
(map-all "é" :w)
|
||||
;; idem pour [W] et [É]
|
||||
(map-all "É" :W)
|
||||
;; idem pour [aw] et [aé]
|
||||
(map-text-object "aé" :aw)
|
||||
;; idem pour [aW] et [aÉ]
|
||||
(map-text-object "aÉ" :aW)
|
||||
;; idem pour [iw] et [ié]
|
||||
(map-text-object "ié" :iw)
|
||||
;; idem pour [iW] et [iÉ]
|
||||
(map-text-object "iÉ" :iW))
|
||||
(𝛅 mapping-movement [] "on préserve {hjkl} pour les directions"
|
||||
(map-all :c :h) (map-all :t :j) (map-all :s :k) (map-all :r :l)
|
||||
(map-all :C :H) ;; ------
|
||||
;; {JKL} devient [TSR]
|
||||
(map-all :T :J) (map-all :S :K) (map-all :R :L) ;; ------
|
||||
;; on préserve les variantes avec 'g'
|
||||
(map-all :gt :gj) (map-all :gs :gk) ;; ------
|
||||
;; on préserve les variantes avec 'z'
|
||||
(map-all :zT :zt) (map-all :zt :zj) (map-all :zk :zs) (map-all :zs :zk)
|
||||
;; ------
|
||||
;; {t} devient [h] pour être proche de [f]
|
||||
(map-all :h :t) ;; idem pour {T} et [H]
|
||||
(map-all :H :T) ;; {c} devient [l]
|
||||
(map-all :l :c) ;; {C} devient [L]
|
||||
(map-all :L :C) ;; {j} devient [r]
|
||||
(map-all :j :r) ;; {J} devient [R]
|
||||
(map-all :J :R) ;; {k} devient [s]
|
||||
(map-all :k :s) ;; {K} devient [S]
|
||||
(map-all :K :S))
|
||||
|
||||
(fn mapping-window []
|
||||
;; [w] est libre pour faire <C-w>
|
||||
(map-normal :w :<C-w>)
|
||||
;; et [w] pour faire <C-w><C-w>
|
||||
(map-normal :W :<C-w><C-w>)
|
||||
;; on map [w]+direction, miniscule + majuscule
|
||||
(map-normal :wc :<C-w>h)
|
||||
(map-normal :wt :<C-w>j)
|
||||
(map-normal :ws :<C-w>k)
|
||||
(map-normal :wr :<C-w>l)
|
||||
(map-normal :wC :<C-w>H)
|
||||
(map-normal :wT :<C-w>J)
|
||||
(map-normal :wS :<C-w>K)
|
||||
(map-normal :wR :<C-w>L)
|
||||
;; crée un split _h_orizontal
|
||||
(map-normal :wh :<C-w>s)
|
||||
;; va en haut à gauche
|
||||
(map-normal "wé" :<C-w>t)
|
||||
;; déplace sur un nouveau tab
|
||||
(map-normal "wÉ" :<C-w>T))
|
||||
(𝛅 mapping-tabs [] ;; le couple [gb]/[gé] agit sur les tabs
|
||||
(map-normal :gb :gT) (map-normal "gé" :gt) ;; [gB] va au premier tab
|
||||
(map-normal :gB ":execute \"silent! tabfirst\"<CR>") ;; [gÉ] au dernier
|
||||
(map-normal "gÉ" ":execute \"silent! tablast\"<CR>")
|
||||
;; [gT] est libéré et peut agir sur les tags
|
||||
(map-normal :gT "<C-]>"))
|
||||
|
||||
(𝛅 mapping-easy-access [] ;; [<] est moins accessible que [«]
|
||||
(map-normal "«" "<") (map-visual "«" :<gv) ;; idem pour [»] et [>]
|
||||
(map-normal "»" ">") (map-visual "»" :>gv)
|
||||
;; idem pour [g,] et [g;] qui sont permutés
|
||||
(map-all "g," "g;") (map-all "g;" "g,")
|
||||
;; [w] est peu accessible, on utilise [é]
|
||||
(map-all "é" :w) ;; idem pour [W] et [É]
|
||||
(map-all "É" :W) ;; idem pour [aw] et [aé]
|
||||
(map-text-object "aé" :aw) ;; idem pour [aW] et [aÉ]
|
||||
(map-text-object "aÉ" :aW) ;; idem pour [iw] et [ié]
|
||||
(map-text-object "ié" :iw) ;; idem pour [iW] et [iÉ]
|
||||
(map-text-object "iÉ" :iW))
|
||||
|
||||
(𝛅 mapping-window [] ;; [w] est libre pour faire <C-w>
|
||||
(map-normal :w :<C-w>) ;; et [w] pour faire <C-w><C-w>
|
||||
(map-normal :W :<C-w><C-w>) ;; on map [w]+direction, miniscule + majuscule
|
||||
(map-normal :wc :<C-w>h) (map-normal :wt :<C-w>j) (map-normal :ws :<C-w>k)
|
||||
(map-normal :wr :<C-w>l) (map-normal :wC :<C-w>H) (map-normal :wT :<C-w>J)
|
||||
(map-normal :wS :<C-w>K) (map-normal :wR :<C-w>L)
|
||||
;; crée un split _h_orizontal
|
||||
(map-normal :wh :<C-w>s) ;; va en haut à gauche
|
||||
(map-normal "wé" :<C-w>t) ;; déplace sur un nouveau tab
|
||||
(map-normal "wÉ" :<C-w>T))
|
||||
|
||||
(fn setup []
|
||||
"Keys that are still free:
|
||||
* , and ; as they may be used as leaders (if you don’t use those as leaders, you may want to swap the two)
|
||||
"In any case, the following keys are always free for you to remap as you see fit:
|
||||
* , and ; as they may be used as leaders (if you don’t use those as leaders,
|
||||
you may want to swap the two)
|
||||
* à and À
|
||||
* ç and Ç
|
||||
* è and È"
|
||||
|
||||
113
gen_doc.fnl
Normal file
113
gen_doc.fnl
Normal file
@ -0,0 +1,113 @@
|
||||
;; bepo.nvim: bepo mapping for neovim
|
||||
;; Copyright 2022 Clément Joly
|
||||
;;
|
||||
;; Licensed under the Apache License, Version 2.0 (the "License");
|
||||
;; you may not use this file except in compliance with the License.
|
||||
;; You may obtain a copy of the License at
|
||||
;;
|
||||
;; http://www.apache.org/licenses/LICENSE-2.0
|
||||
;;
|
||||
;; Unless required by applicable law or agreed to in writing, software
|
||||
;; distributed under the License is distributed on an "AS IS" BASIS,
|
||||
;; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
;; See the License for the specific language governing permissions and
|
||||
;; limitations under the License.
|
||||
;;
|
||||
|
||||
(local fennel (require :fennel))
|
||||
|
||||
(fn ==== []
|
||||
(print (string.rep "=" 80)))
|
||||
|
||||
(fn ---- []
|
||||
(print (string.rep "-" 80)))
|
||||
|
||||
(fn right-align [str max]
|
||||
(let [len (length str)]
|
||||
(.. str (string.rep " " (- max len)))))
|
||||
|
||||
(fn print-mapping-struct [struct]
|
||||
(match struct
|
||||
{: bepo : modes : qwerty}
|
||||
(print (string.format "%6s %5s %s" modes bepo qwerty))
|
||||
_ (error (.. "Received an invalid struct" (fennel.view struct)))))
|
||||
|
||||
(fn print-lua-import [name]
|
||||
(->> (values (right-align (string.format "require(\"bepo\").%s()" name) 46)
|
||||
(.. :*bepo.nvim- name "*"))
|
||||
(string.format "%s %35s")
|
||||
(print)))
|
||||
|
||||
(set _G.gen-doc true)
|
||||
(local bepo (require :fnl/bepo))
|
||||
|
||||
;; Content of the help file
|
||||
(print "*bepo.nvim* mappings for the bépo layout <https://bepo.fr>
|
||||
|
||||
|
||||
|
||||
Author: Clément Joly <https://cj.rs/contact>
|
||||
Homepage: <https://cj.rs/bepo-nvim>
|
||||
License: APACHE license
|
||||
|
||||
|
||||
Type |gO| to see the table of contents.
|
||||
")
|
||||
|
||||
(====)
|
||||
|
||||
(print "USAGE *bepo.nvim-usage*
|
||||
|
||||
For a basic setup with all mappings defined, just add the following to your
|
||||
init.lua:
|
||||
*bepo.nvim-setup*
|
||||
|
||||
require(\"bepo\").setup()
|
||||
|
||||
See |bepo.nvim-cherry-pick| to apply only some groups of mapping. By default,
|
||||
setup() applies all mapping groups.
|
||||
")
|
||||
|
||||
(print " *bepo.nvim-always-free*")
|
||||
|
||||
(print (fennel.metadata:get bepo.setup :fnl/docstring))
|
||||
(print "")
|
||||
|
||||
(====)
|
||||
(print "MAPPING CHERRY-PICK *bepo.nvim-cherry-pick*
|
||||
|
||||
You can also pick only some groups of mapping, for instance because you have
|
||||
your own preferences for some key that don’t match this extension. To apply
|
||||
only the “window” and “movement” groups of mapping, use this instead of
|
||||
|bepo.nvim-setup| in your init.lua:
|
||||
|
||||
require(\"bepo\").movement()
|
||||
require(\"bepo\").window()
|
||||
|
||||
The following subsections go into details of exactly what mappings are
|
||||
in each group. “Modes” have the same meaning as in the |map-table|.
|
||||
")
|
||||
|
||||
(let [tbl (collect [name docstruct (pairs bepo)]
|
||||
(if (= name :setup)
|
||||
nil
|
||||
(values name docstruct)))]
|
||||
(do
|
||||
(table.sort tbl)
|
||||
(each [name docstruct (pairs tbl)]
|
||||
(do
|
||||
(----)
|
||||
(print-lua-import name)
|
||||
(-?> docstruct (?. :docstring) print)
|
||||
(print "")
|
||||
(if (> (length docstruct.body) 0)
|
||||
(print-mapping-struct {:bepo :Bepo :modes :Modes :qwerty :Qwerty}))
|
||||
(each [_ mapping-struct (pairs docstruct.body)]
|
||||
(match mapping-struct
|
||||
{:comment c} (print c)
|
||||
_ (print-mapping-struct mapping-struct)))
|
||||
(print "")))))
|
||||
|
||||
;; We split the vim and the : to prevent vim from picking up that for the fennel file
|
||||
(print (.. "\nvim" ":tw=78:ts=8:ft=help:norl:"))
|
||||
|
||||
120
help/bepo-nvim.txt
Normal file
120
help/bepo-nvim.txt
Normal file
@ -0,0 +1,120 @@
|
||||
*bepo.nvim* mappings for the bépo layout <https://bepo.fr>
|
||||
|
||||
|
||||
|
||||
Author: Clément Joly <https://cj.rs/contact>
|
||||
Homepage: <https://cj.rs/bepo-nvim>
|
||||
License: APACHE license
|
||||
|
||||
|
||||
Type |gO| to see the table of contents.
|
||||
|
||||
================================================================================
|
||||
USAGE *bepo.nvim-usage*
|
||||
|
||||
For a basic setup with all mappings defined, just add the following to your
|
||||
init.lua:
|
||||
*bepo.nvim-setup*
|
||||
|
||||
require("bepo").setup()
|
||||
|
||||
See |bepo.nvim-cherry-pick| to apply only some groups of mapping. By default,
|
||||
setup() applies all mapping groups.
|
||||
|
||||
*bepo.nvim-always-free*
|
||||
In any case, the following keys are always free for you to remap as you see fit:
|
||||
* , and ; as they may be used as leaders (if you don’t use those as leaders,
|
||||
you may want to swap the two)
|
||||
* à and À
|
||||
* ç and Ç
|
||||
* è and È
|
||||
|
||||
================================================================================
|
||||
MAPPING CHERRY-PICK *bepo.nvim-cherry-pick*
|
||||
|
||||
You can also pick only some groups of mapping, for instance because you have
|
||||
your own preferences for some key that don’t match this extension. To apply
|
||||
only the “window” and “movement” groups of mapping, use this instead of
|
||||
|bepo.nvim-setup| in your init.lua:
|
||||
|
||||
require("bepo").movement()
|
||||
require("bepo").window()
|
||||
|
||||
The following subsections go into details of exactly what mappings are
|
||||
in each group. “Modes” have the same meaning as in the |map-table|.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
require("bepo").movement() *bepo.nvim-movement*
|
||||
on préserve {hjkl} pour les directions
|
||||
|
||||
Modes Bepo Qwerty
|
||||
nx c h
|
||||
nx t j
|
||||
nx s k
|
||||
nx r l
|
||||
nx C H
|
||||
nx T J
|
||||
nx S K
|
||||
nx R L
|
||||
nx gt gj
|
||||
nx gs gk
|
||||
nx zT zt
|
||||
nx zt zj
|
||||
nx zk zs
|
||||
nx zs zk
|
||||
nx h t
|
||||
nx H T
|
||||
nx l c
|
||||
nx L C
|
||||
nx j r
|
||||
nx J R
|
||||
nx k s
|
||||
nx K S
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
require("bepo").window() *bepo.nvim-window*
|
||||
|
||||
Modes Bepo Qwerty
|
||||
n w <C-w>
|
||||
n W <C-w><C-w>
|
||||
n wc <C-w>h
|
||||
n wt <C-w>j
|
||||
n ws <C-w>k
|
||||
n wr <C-w>l
|
||||
n wC <C-w>H
|
||||
n wT <C-w>J
|
||||
n wS <C-w>K
|
||||
n wR <C-w>L
|
||||
n wh <C-w>s
|
||||
n wé <C-w>t
|
||||
n wÉ <C-w>T
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
require("bepo").easy_access() *bepo.nvim-easy_access*
|
||||
|
||||
Modes Bepo Qwerty
|
||||
n « <
|
||||
v « <gv
|
||||
n » >
|
||||
v » >gv
|
||||
nx g, g;
|
||||
nx g; g,
|
||||
nx é w
|
||||
nx É W
|
||||
ox aé aw
|
||||
ox aÉ aW
|
||||
ox ié iw
|
||||
ox iÉ iW
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
require("bepo").tabs() *bepo.nvim-tabs*
|
||||
|
||||
Modes Bepo Qwerty
|
||||
n gb gT
|
||||
n gé gt
|
||||
n gB :execute "silent! tabfirst"<CR>
|
||||
n gÉ :execute "silent! tablast"<CR>
|
||||
n gT <C-]>
|
||||
|
||||
|
||||
vim:tw=78:ts=8:ft=help:norl:
|
||||
Loading…
x
Reference in New Issue
Block a user