docvim: Documentation generator for Vim plug-ins

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Produces Vim help and HTML (via Markdown) documentation.


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.2.0.0, 0.3.0.0, 0.3.1.0, 0.3.1.1, 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
Change log None available
Dependencies base (>=4.8 && <4.10), containers, directory, dlist, docvim, filepath, lens, mtl, optparse-applicative, parsec, pretty-show, split [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.1.1)
Uploaded by wincent at 2016-06-15T07:42:07Z

Modules

[Index]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for docvim-0.3.1.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

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

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
git commit -p # git tag, git push --follow-tags etc...
cabal check
cabal sdist
open dist # upload candidate to https://hackage.haskell.org/packages/candidates/upload
cabal upload dist/docvim-$VERSION.tar.gz

Examples of plug-ins using docvim

FAQ

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

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