mini-doc.md

Generation of help files from EmmyLua-like annotations

See more details in help file.

This is a part of mini.nvim library. See its repository page to learn about common design principles and configuration recipes.

If you want to help this project grow but don't know where to start, check out contributing guides or leave a Github star for 'mini.nvim' project.

Demo

demo-doc.mp4

Features

• Keep documentation next to code by writing EmmyLua-like annotation comments. They will be parsed as is, so formatting should follow built-in guide. However, custom hooks are allowed at many generation stages for more granular management of output help file.
• Generation is done by processing a set of ordered files line by line. Each line can either be considered as a part of documentation block (if it matches certain configurable pattern) or not (considered to be an "afterline" of documentation block). See MiniDoc.generate() help for more details.
• Processing is done by using nested data structures (section, block, file, doc) describing certain parts of help file. See MiniDoc-data-structures help page for more details.
• Allow flexible customization of output via hook functions.
• Project specific script can be written as plain Lua file with configuratble path. See MiniDoc.generate() help for more details.

Installation

There are two branches to install from:

• main (default, recommended) will have latest development version of plugin. All changes since last stable release should be perceived as being in beta testing phase (meaning they already passed alpha-testing and are moderately settled).
• stable will be updated only upon releases with code tested during public beta-testing phase in main branch.

Here are code snippets for some common installation methods (use only one):

• Using wbthomason/packer.nvim:

Branch	Code snippet
Main	use 'echasnovski/mini.nvim'
Stable	use { 'echasnovski/mini.nvim', branch = 'stable' }

• Using junegunn/vim-plug:

Branch	Code snippet
Main	Plug 'echasnovski/mini.nvim'
Stable	Plug 'echasnovski/mini.nvim', { 'branch': 'stable' }

Important: don't forget to call require('mini.doc').setup() to enable its functionality.

Note: if you are on Windows, there might be problems with too long file paths (like error: unable to create file <some file name>: Filename too long). Try doing one of the following:

• Enable corresponding git global config value: git config --system core.longpaths true. Then try to reinstall.
• Install plugin in other place with shorter path.

Default config

-- No need to copy this inside `setup()`. Will be used automatically.
{
  -- Lua string pattern to determine if line has documentation annotation.
  -- First capture group should describe possible section id. Default value
  -- means that annotation line should:
  -- - Start with `---` at first column.
  -- - Any non-whitespace after `---` will be treated as new section id.
  -- - Single whitespace at the start of main text will be ignored.
  annotation_pattern = '^%-%-%-(%S*) ?',

  -- Identifier of block annotation lines until first captured identifier
  default_section_id = '@text',

  -- Hooks to be applied at certain stage of document life cycle. Should
  -- modify its input in place (and not return new one).
  hooks = {
    -- Applied to block before anything else
    block_pre = --<function: infers header sections (tag and/or signature)>,

    -- Applied to section before anything else
    section_pre = --<function: replaces current aliases>,

    -- Applied if section has specified captured id
    sections = {
      ['@alias'] = --<function: registers alias in MiniDoc.current.aliases>,
      ['@class'] = --<function>,
      -- For most typical usage see |MiniDoc.afterlines_to_code|
      ['@eval'] = --<function: evaluates lines; replaces with their return>,
      ['@field'] = --<function>,
      ['@param'] = --<function>,
      ['@private'] = --<function: registers block for removal>,
      ['@return'] = --<function>,
      ['@seealso'] = --<function>,
      ['@signature'] = --<function: formats signature of documented object>,
      ['@tag'] = --<function: turns its line in proper tag lines>,
      ['@text'] = --<function: purposefully does nothing>,
      ['@type'] = --<function>,
      ['@usage'] = --<function>,
    },

    -- Applied to section after all previous steps
    section_post = --<function: currently does nothing>,

    -- Applied to block after all previous steps
    block_post = --<function: does many things>,

    -- Applied to file after all previous steps
    file = --<function: adds separator>,

    -- Applied to doc after all previous steps
    doc = --<function: adds modeline>,
  },

  -- Path (relative to current directory) to script which handles project
  -- specific help file generation (like custom input files, hooks, etc.).
  script_path = 'scripts/minidoc.lua',
}

Similar plugins

• tjdevries/tree-sitter-lua
• numToStr/lemmy-help (command line tool)