Documenting Plugins

Since September 2020, Kakoune's :doc command will search for and render documentation loaded from plugins. To make it as easy as possible for your users to understand and use your plugin, it's helpful to follow these conventions for documentation.

What documentation goes where?

There are many different types of documentation, and different places to put them. To avoid duplication and make the documentation easier to maintain, it's best to only put a piece of documentation in the place it's most likely to be found.

Your README should contain a description of what the plugin does, and why somebody might want to install it. It should also describe any external dependencies the plugin requires, and how to install it, especially if it's more complicated than a basic plugin. You can link to Installing plugins if you don't want to write out the basic installation instructions yourself.

If your plugin provides custom commands, make sure they provide a docstring (with the -docstring option) that describes what they do, what switches and what arguments they take. Be complete, but don't provide examples or cross-references - the info box can't be scrolled, so space is limited. You don't need to write docstrings for commands not intended for end-users (particularly those define with the -hidden flag), unless you really want to.

If your plugin provides custom options, provide a docstring (with the -docstring option) for those too. Just like commands, be complete but concise, and you don't have to document -hidden options.

Every other kind of documentation should be put in the plugin's documentation file. Assuming your plugin is called "MyPlugin", you might wind up with a structure like this:

kakoune-myplugin
  |
  +- README.md (Your plugin's README file)
  |
  +- myplugin.kak (The actual plugin code, with docstrings)
  |
  +- myplugin.asciidoc (The documentation file)

See "What should I document?" below for suggestions about what to put in the documentation file.

What syntax do I use?

Kakoune's online documentation browser renders Asciidoc markup. It doesn't support every corner of the Asciidoc spec, but it covers the basics.

Kakoune does support Asciidoc's fragment-identifier syntax:

[[some-fragment]]
The preceding line will not be displayed
in the resulting document, but a link to "#some-fragment"
will take the user straight here.

Not only will links to fragment-identifiers work, but Kakoune will also complete fragment-identifiers for the second argument of the :doc command. Kakoune also creates a fragment identifier for every second-level heading (a single line beginning with ##).

When creating hyperlinks, you must use syntax like this:

<<document,label>>
<<document#target,label>>

The first syntax shows "label", but if the user hits <ret>, Kakoune will effectively execute :doc document. Hitting <ret> on the second example is equivalent to executing :doc document target.

These syntaxes will not work:

<<#target,label>>           Document is required
<<path/to/document,label>>  Paths are not supported

What should I document?

Not every plugin requires every one of these, but if you're wondering what to write about, here's some suggestions.

Overview

This is somewhat redundant with the README, but this can be a bit more detailed than the README's quick sales-pitch. You might also want to provide some example mappings or point out options the user should set before using your plugin.

Tutorial

If you can write a completely deterministic tour through the functionality of your plugin, that would be a good thing to put in the documentation.

If your plugin has external dependencies (like a plugin that integrates with a build system, so you need a project that uses the build system in order to use the plugin), a tutorial is not practical - once there's too many "if you have A the output should look like B, if you have C the output should look like D" conditionals, it gets too confusing to be helpful.

How-to guides

If there's any particularly common environments or work-flows for your plugin, you may want to document them specially.

For example, macOS is unusual because there's no official package repository like other Unix-based systems have, and because the GUI is not based on X11 like other Unix-based systems use. If your plugin touches either of those areas, you may wish to write a special guide to configuring and using your plugin on macOS.

As another example, many people use Kakoune inside tmux, and tmux is far more flexible than other windowing systems Kakoune supports. If your plugin includes some kind of user-interface element, you may wish to write a special guide to making the best use of it inside tmux.

Explanations

If your plugin has more than one command, or a command and an option, they probably interact in surprisng ways - maybe one command only works if the other command has already been run once, or the option must be set to a non-empty value, that kind of thing.

You should describe how the various parts of your plugin interact, and try to give the user a mental model of how things are supposed to work.

In particular, if your plugin has any limitations or known bugs (such as arithmetic being subject to the limitations of the POSIX shell, or failing to account for non-ASCII characters), mention those here.

Reference material

The most important reference material is already in the docstrings of your commands and options, so that doesn't need to be repeated. However, you may want to document other list of important things, like:

• Common failure modes and error messages, what they mean and how to resolve them
• Any environment variables that affect the operation of your plugin ($HOME, $TMPDIR, $XDG_CACHE_HOME, etc.)
• Any files your plugin reads or looks for, such as config files, external tools (to enable integration with that tool), etc.