Skip to content
Documentation generator for Vim plug-ins
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
dist
lib/Text/Docvim
src
tests
.gitignore
.tmux
.travis.yml
.watchmanconfig
CHANGELOG.md
LICENSE.md
README.md
Setup.hs
docvim.cabal
stack.yaml

README.md

docvim: a documentation generator for Vim plug-ins

Build Status docvim on Stackage LTS 3 docvim on Stackage Nightly

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

Quickstart

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

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

Usage

docvim - a documentation generator for Vim plug-ins

Usage: docvim [--version] [OUTFILES...] [-d|--debug] [-c|--directory DIRECTORY]
              [-v|--verbose]
  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

Installation

# Stack:
stack install docvim

# Cabal:
cabal install docvim

Syntax

""
" 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)

Annotations

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

Development

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.

Set-up

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

Running

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

Building

stack build --file-watch

Building and viewing the code-level documentation

# Stack:
stack haddock
open .stack-work/dist/x86_64-osx/Cabal-1.22.5.0/doc/html/docvim/index.html

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

Testing

# 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.

Linting

# 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...
bin/sdist
bin/upload

Links

Examples of plug-ins using docvim

FAQ

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

You can’t perform that action at this time.