Generating Readmes

[jojojames]

@noctuid I was curious what you thought of annalist and generating readmes of the mode bindings?

I think it'd be cool to have something (not sure if already there) where we can query annalist for specific keymaps and have it return a table we can use in a readme.

e.g. something like this already looks 99% of the way there for a readme.

* ~deadgrep-mode-map~
** Normal
| Key          | Definition                           | Previous |
|--------------+--------------------------------------+----------|
| =RET=        | ~deadgrep-visit-result~              | ~nil~    |
| =<S-return>= | ~deadgrep-visit-result-other-window~ | ~nil~    |
| =g o=        | ~deadgrep-visit-result-other-window~ | ~nil~    |
| =g r=        | ~deadgrep-restart~                   | ~nil~    |
| =C-j=        | ~deadgrep-forward~                   | ~nil~    |
| =C-k=        | ~deadgrep-backward~                  | ~nil~    |
| =TAB=        | ~deadgrep-toggle-file-results~       | ~nil~    |
| =i=          | ~deadgrep-edit-mode~                 | ~nil~    |
| =q=          | ~quit-window~                        | ~nil~    |
| =Z Z=        | ~quit-window~                        | ~nil~    |
| =Z Q=        | ~evil-quit~                          | ~nil~    |

[noctuid]

Yeah, you can create a view with a predicate (e.g. (lambda (keymap) (eq keymap 'deadgrep-mode-map)). Another way to do it that might be more convenient would be to just run emacs in batch mode, load a single evil-collection file, and then put the results of annalist-describe in a file. It would be pretty simple to write a make target to do this for every file (especially if the keybindings were in their own org file, so you could just overwrite it completely).

[michaelbogdan]

Do you want to generate a catalogue out of all keybinding maps for all the modes, like a evil-collection-*-map.org, linked to from a master readme? I am not entirely sure what the benefit would be, as the respective .el files are extremely readable the way the are. The only added value would be to see which keys are overwritten, which is relevant with something like dired but not so much with modes where most keys aren't used anyhow.

[jojojames]

It'd be similar to https://github.com/emacs-evil/evil-collection/tree/master/modes/ediff or https://github.com/emacs-evil/evil-magit/blob/master/README.org which has keybindings, some documentation around certain defcustoms, gotchas, etc.

I think we can probably just generate an initial set of docs using @noctuid 's annalist and then manually change them later to polish them up.

Automating it would be cool but I'm thinking about the complications around adding extra documentation other than keybindings.

[michaelbogdan]

Well, it is the "extra documentation" that would be really interesting, like rationale for certain bindings or interplay between two different packages. :)

I think a reasonable first step would be to produce such a readme without the key map part by hand as a proof-of-concept. A second step is to automatically generate the keybindings, and since annalist generates org files anyhow, to add an optional, manual heading with additional notes or such.

[jojojames]

I think readme's with keybindings should be the first step. Some people, I suspect, just don't like browsing code when trying to figure out keybindings. A nice web view with a list of keybindings in a pretty table is probably more palatable.

I think most packages don't really need extravagant documentation so the the extra documentation would be a cherry on top, IMO.

[noctuid]

I think we can probably just generate an initial set of docs using @noctuid 's annalist and then manually change them later to polish them up.

Should be possible to have it completely automated (would be easier especially if you ever wanted to change the formatting or sorting later). Like a package like org-toc (automatic table of contents insertion), annalist could provide a way to insert/replace a table under a specific heading (and potentially with a filter if you wanted to split the keybindings for a file into multiple sections).