docvim: Documentation generator for Vim plug-ins

[ development, library, mit, program ] [ Propose Tags ]

Produces Vim help and HTML (via Markdown) documentation.


[Skip to Readme]

Modules

[Last Documentation]

  • Docvim
    • Docvim.AST
    • Docvim.CLI
    • Docvim.Compile
    • Docvim.Options
    • Docvim.Parse
    • Printer
      • Docvim.Printer.Markdown
      • Docvim.Printer.Vim
    • Docvim.ReadDir
    • Docvim.Util
    • Docvim.Visitor
      • Docvim.Visitor.Command
      • Docvim.Visitor.Commands
      • Docvim.Visitor.Footer
      • Docvim.Visitor.Function
      • Docvim.Visitor.Functions
      • Docvim.Visitor.Heading
      • Docvim.Visitor.Mapping
      • Docvim.Visitor.Mappings
      • Docvim.Visitor.Option
      • Docvim.Visitor.Options
      • Docvim.Visitor.Plugin
      • Docvim.Visitor.Section
      • Docvim.Visitor.Symbol
  • Paths_docvim

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

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 && <4.9), 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.2.0.0)
Uploaded by wincent at 2016-06-09T15:10:15Z
Distributions
Executables docvim
Downloads 8363 total (16 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2016-11-24 [all 1 reports]

Readme for docvim-0.2.0.0

[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

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
  • @dedent
  • @footer
  • @function
  • @indent
  • @mapping
  • @mappings
  • @option
  • @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 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.

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