Monthly Downloads: 29
Programming language: Haskell
License: MIT License
Tags: Development    
Latest version: v0.3.2.1

docvim alternatives and similar packages

Based on the "Development" category.
Alternatively, view docvim alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of docvim or a related project?

Add another 'Development' Package


docvim: a documentation generator for Vim plug-ins

docvim is a documentation generator for Vim plug-ins, written in Haskell.


# Print Markdown-formatted help documentation for files in current directory

# Write Markdown README + Vim help text file for $PLUGIN
docvim -c ~/code/$PLUGIN ~/code/$PLUGIN/doc/$PLUGIN.txt ~/code/$PLUGIN/README.md


docvim - a documentation generator for Vim plug-ins

Usage: docvim [--version] [OUTFILES...] [-d|--debug] [-c|--directory DIRECTORY]
  Generate documentation for a Vim plug-in

Available options:
  -h,--help                Show this help text
  --version                Print version information
  OUTFILES...              Target file(s) for generated output (default:
                           standard output)
  -d,--debug               Print debug information during processing
  -c,--directory DIRECTORY Change to DIRECTORY before processing (default: ".")
  -v,--verbose             Be verbose during processing


# Stack:
stack install docvim

# Cabal:
cabal install docvim


" Docblocks start with a pair of double quotes, followed
" by standard Vim comments (with a double quote prefix)
" containing Markdown-like text and optional annotations
" that look like this:
" ```
" @command :Ack {pattern} {options}
" ```

Supported Markdown features

# Top-level heading

## Sub-heading

--- (Horizontal dividers)

> Blockquote

`inline code`

fenced codeblocks (leading space syntax not supported)

![alt text](http://example.com/image.jpg)
(becomes a link in vimdoc, but an image in markdown)

- Lists.

Unsupported Markdown syntax

*foo* (emphasis; turns into Vim doc targets instead)

*,+ (list syntax; just use - instead)

<html> (we don't want ambiguity with things like <leader> and so on)


  • @command
  • @commands
  • @dedent
  • @footer
  • @function
  • @functions
  • @indent
  • @mapping
  • @mappings
  • @option
  • @options
  • @plugin


Convenience wrappers

bin/accept  # Accept current "golden" test output.
bin/docvim  # Run the docvim executable.
bin/golden  # Run just the "golden" tests.
bin/haddock # Produce Haddock documentation.
bin/lint    # Run the linter.
bin/tasty   # Run just the Tasty tests.
bin/test    # Run all tests, including lints.

These are wrappers for the explicit invocations described below.


You can set-up a development environment using [Stack] (recommended) or Cabal:

# Stack:
brew install stack
stack build

# Cabal:
brew install cabal-install
cabal sandbox init
cabal install --only-dependencies --enable-tests
cabal build


Run using stack exec (or cabal run) and passing in docvim-specific OPTIONS:

# Stack:
stack exec docvim [OPTIONS]

# Cabal:
cabal run -- [OPTIONS]

You can also run the modules from inside the REPL:

# Stack:
stack repl
> pp "let l:test=1" -- pretty-prints AST

# Cabal:
cabal repl
> import Text.Docvim.Parse
> pp "let l:test=1" -- pretty-prints AST


stack build --file-watch

Building and viewing the code-level documentation

# Stack:
stack haddock
open .stack-work/dist/x86_64-osx/Cabal-

# Cabal:
cabal haddock --executables
open dist/doc/html/docvim/docvim/index.html


# Stack:
stack test        # Runs all test suites, including linting.
stack test :tasty # Runs just the Tasty test suite.

# Cabal:
cabal test       # Runs all test suites, including linting.
cabal test tasty # Runs just the Tasty test suite.

Updating "golden" files

# Stack:
stack test --test-arguments=--accept          # Runs all test suites.
stack test :tasty --test-arguments=--accept   # Runs just the Tasty test suite.

# Cabal:
cabal test --test-options=---accept           # Runs all test suites.
cabal test tasty --test-options=---accept     # Runs just the Tasty test suite.


# Stack:
stack test              # Runs linter as part of overall set of suites.
stack test :hlint       # Runs linter alone.

# Cabal:
cabal install hlint     # (First-time only).
cabal test              # Runs linter as part of overall set of suites.
cabal test hlint        # Runs linter alone.

hlint src               # If you have HLint installed under $PATH.

Release process

vim docvim.cabal # Update version number in two places.
vim CHANGELOG.md # Update, er, changelog.
git commit -p # git tag, git push --follow-tags etc...


Examples of plug-ins using docvim


Why a new tool and not an existing one like Vimdoc?

  • I wanted to target multiple output formats (Vim help files and Markdown).
  • I wanted total control over the presentation of the output.
  • It's fun to build new things from scratch.
  • The project is a great fit for my learn-me-a-Haskell goal this year.

Why is it called "docvim"?

"Vimdoc" was the first name that occurred to me when I started this project, but:

So, in a remarkable flash of profound creativity, I settled on "docvim" instead, which right now yields this pleasing search result:

Did you mean: dacvim