docvim: Documentation generator for Vim plug-ins

[ development, library, mit, program ] [ Propose Tags ] [ Report a vulnerability ]

Produces Vim help and HTML (via Markdown) documentation.

[Skip to Readme]

Downloads

docvim-0.3.2.1.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

wincent

For package maintainers and hackage trustees

edit package information

Candidates

0.1.0.0, 0.2.0.0, 0.3.0.0, 0.3.1.0, 0.3.1.1, 0.3.1.2, 0.3.1.3

Versions [RSS]	0.1.0.0, 0.2.0.0, 0.3.0.0, 0.3.1.0, 0.3.1.1, 0.3.1.2, 0.3.1.3, 0.3.1.4, 0.3.1.5, 0.3.1.6, 0.3.2.0, 0.3.2.1
Dependencies	base (>=4.8.2.0 && <5), containers (>=0.5.6.2), directory (>=1.2.2.0), dlist (>=0.7.1.2), docvim (>=0.3.2.1), filepath (>=1.4.0.0), lens (>=4.13), mtl (>=2.2.1), optparse-applicative (>=0.12.1.0), parsec (>=3.1.11), pretty-show (>=1.6.10), split (>=0.2.3.1) [details]
License	MIT
Copyright	2015-present Greg Hurrell
Author	Greg Hurrell
Maintainer	greg@hurrell.net
Category	Development
Home page	https://github.com/wincent/docvim
Source repo	head: git clone https://github.com/wincent/docvim.git this: git clone https://github.com/wincent/docvim.git(tag 0.3.2.1)
Uploaded	by wincent at 2016-06-26T06:26:19Z
Distributions
Executables	docvim
Downloads	8432 total (26 in the last 30 days)
Rating	(no votes yet) [estimated by Bayesian average]
Your Rating	λ λ λ
Status	Docs available [build log] Last success reported on 2016-06-26 [all 1 reports]

Readme for docvim-0.3.2.1

[back to package description]

docvim: a documentation generator for Vim plug-ins

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 haskell-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

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:

The number one hit for "vimdoc" is this online copy of Vim's own documentation.
The name "Vimdoc" is already taken by a similar project.

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