Hackage :: [Package]

docvim: Documentation generator for Vim plug-ins

[ development, library, mit, program ] [ Propose Tags ] [ Report a vulnerability ]
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 8581 total (32 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

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

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