README.md

   1 # docvim: a documentation generator for Vim plug-ins
   2
   3 [![Build Status](https://travis-ci.org/wincent/docvim.svg?branch=master)](https://travis-ci.org/wincent/docvim) [![docvim on Stackage LTS 3](http://stackage.org/package/docvim/badge/lts)](http://stackage.org/lts/package/docvim) [![docvim on Stackage Nightly](http://stackage.org/package/docvim/badge/nightly)](http://stackage.org/nightly/package/docvim)
   4
   5 docvim is a documentation generator for Vim plug-ins, written in Haskell.
   6
   7 ## Quickstart
   8
   9 ```bash
  10 # Print Markdown-formatted help documentation for files in current directory
  11 docvim
  12
  13 # Write Markdown README + Vim help text file for $PLUGIN
  14 docvim -c ~/code/$PLUGIN ~/code/$PLUGIN/doc/$PLUGIN.txt ~/code/$PLUGIN/README.md
  15 ```
  16
  17 ## Usage
  18
  19 ```
  20 docvim - a documentation generator for Vim plug-ins
  21
  22 Usage: docvim [--version] [OUTFILES...] [-d|--debug] [-c|--directory DIRECTORY]
  23               [-v|--verbose]
  24   Generate documentation for a Vim plug-in
  25
  26 Available options:
  27   -h,--help                Show this help text
  28   --version                Print version information
  29   OUTFILES...              Target file(s) for generated output (default:
  30                            standard output)
  31   -d,--debug               Print debug information during processing
  32   -c,--directory DIRECTORY Change to DIRECTORY before processing (default: ".")
  33   -v,--verbose             Be verbose during processing
  34 ```
  35
  36 ## Installation
  37
  38 ```
  39 # Stack:
  40 stack install docvim
  41
  42 # Cabal:
  43 cabal install docvim
  44 ```
  45
  46 ## Syntax
  47
  48 ```vim
  49 ""
  50 " Docblocks start with a pair of double quotes, followed
  51 " by standard Vim comments (with a double quote prefix)
  52 " containing Markdown-like text and optional annotations
  53 " that look like this:
  54 "
  55 " ```
  56 " @command :Ack {pattern} {options}
  57 " ```
  58 ```
  59
  60 ### Supported Markdown features
  61
  62     # Top-level heading
  63
  64     ## Sub-heading
  65
  66     --- (Horizontal dividers)
  67
  68     > Blockquote
  69
  70     `inline code`
  71
  72     ```
  73     fenced codeblocks (leading space syntax not supported)
  74     ```
  75
  76     ![alt text](http://example.com/image.jpg)
  77     (becomes a link in vimdoc, but an image in markdown)
  78
  79     - Lists.
  80
  81 ### Unsupported Markdown syntax
  82
  83 ```
  84 *foo* (emphasis; turns into Vim doc targets instead)
  85
  86 *,+ (list syntax; just use - instead)
  87
  88 <html> (we don't want ambiguity with things like <leader> and so on)
  89 ```
  90
  91 ### Annotations
  92
  93 - `@command`
  94 - `@commands`
  95 - `@dedent`
  96 - `@footer`
  97 - `@function`
  98 - `@functions`
  99 - `@indent`
 100 - `@mapping`
 101 - `@mappings`
 102 - `@option`
 103 - `@options`
 104 - `@plugin`
 105
 106 ## Development
 107
 108 ### Convenience wrappers
 109
 110 ```bash
 111 bin/accept  # Accept current "golden" test output.
 112 bin/docvim  # Run the docvim executable.
 113 bin/golden  # Run just the "golden" tests.
 114 bin/haddock # Produce Haddock documentation.
 115 bin/lint    # Run the linter.
 116 bin/tasty   # Run just the Tasty tests.
 117 bin/test    # Run all tests, including lints.
 118 ```
 119
 120 These are wrappers for the explicit invocations described below.
 121
 122 ### Set-up
 123
 124 You can set-up a development environment using [Stack] (recommended) or [Cabal]:
 125
 126 ```bash
 127 # Stack:
 128 brew install haskell-stack
 129 stack build
 130
 131 # Cabal:
 132 brew install cabal-install
 133 cabal sandbox init
 134 cabal install --only-dependencies --enable-tests
 135 cabal build
 136 ```
 137
 138 ### Running
 139
 140 Run using `stack exec` (or `cabal run`) and passing in docvim-specific `OPTIONS`:
 141
 142 ```bash
 143 # Stack:
 144 stack exec docvim [OPTIONS]
 145
 146 # Cabal:
 147 cabal run -- [OPTIONS]
 148 ```
 149
 150 You can also run the modules from inside the REPL:
 151
 152 ```bash
 153 # Stack:
 154 stack repl
 155 > pp "let l:test=1" -- pretty-prints AST
 156
 157 # Cabal:
 158 cabal repl
 159 > import Text.Docvim.Parse
 160 > pp "let l:test=1" -- pretty-prints AST
 161 ```
 162
 163 ### Building
 164
 165 ```bash
 166 stack build --file-watch
 167 ```
 168
 169 ### Building and viewing the code-level documentation
 170
 171 ```bash
 172 # Stack:
 173 stack haddock
 174 open .stack-work/dist/x86_64-osx/Cabal-1.22.5.0/doc/html/docvim/index.html
 175
 176 # Cabal:
 177 cabal haddock --executables
 178 open dist/doc/html/docvim/docvim/index.html
 179 ```
 180
 181 ### Testing
 182
 183 ```bash
 184 # Stack:
 185 stack test        # Runs all test suites, including linting.
 186 stack test :tasty # Runs just the Tasty test suite.
 187
 188 # Cabal:
 189 cabal test       # Runs all test suites, including linting.
 190 cabal test tasty # Runs just the Tasty test suite.
 191 ```
 192
 193 #### Updating "golden" files
 194
 195 ```bash
 196 # Stack:
 197 stack test --test-arguments=--accept          # Runs all test suites.
 198 stack test :tasty --test-arguments=--accept   # Runs just the Tasty test suite.
 199
 200 # Cabal:
 201 cabal test --test-options=---accept           # Runs all test suites.
 202 cabal test tasty --test-options=---accept     # Runs just the Tasty test suite.
 203 ```
 204
 205 ### Linting
 206
 207 ```bash
 208 # Stack:
 209 stack test              # Runs linter as part of overall set of suites.
 210 stack test :hlint       # Runs linter alone.
 211
 212 # Cabal:
 213 cabal install hlint     # (First-time only).
 214 cabal test              # Runs linter as part of overall set of suites.
 215 cabal test hlint        # Runs linter alone.
 216
 217 hlint src               # If you have HLint installed under $PATH.
 218 ```
 219
 220 ### Release process
 221
 222 ```bash
 223 vim docvim.cabal # Update version number in two places.
 224 vim CHANGELOG.md # Update, er, changelog.
 225 git commit -p # git tag, git push --follow-tags etc...
 226 bin/sdist
 227 bin/upload
 228 ```
 229
 230 ## Links
 231
 232 - [Hackage package](https://hackage.haskell.org/package/docvim)
 233
 234 ### Examples of plug-ins using docvim
 235
 236 - [Ferret](https://github.com/wincent/ferret)
 237 - [Pinnacle](https://github.com/wincent/pinnacle)
 238 - [Scalpel](https://github.com/wincent/scalpel)
 239 - [vim-docvim](https://github.com/wincent/vim-docvim)
 240
 241 ## FAQ
 242
 243 ### Why a new tool and not an existing one like [Vimdoc]?
 244
 245 * I wanted to target multiple output formats (Vim help files and Markdown).
 246 * I wanted total control over the presentation of the output.
 247 * It's fun to build new things from scratch.
 248 * The project is a great fit for my learn-me-a-Haskell goal this year.
 249
 250 ### Why is it called "docvim"?
 251
 252 "Vimdoc" was the first name that occurred to me when I started this project, but:
 253
 254 * The number one hit for "vimdoc" is [this online copy of Vim's own documentation](http://vimdoc.sourceforge.net/).
 255 * The name "Vimdoc" is already taken by [a similar project](https://github.com/google/vimdoc).
 256
 257 So, in a remarkable flash of profound creativity, I settled on "docvim" instead, which right now yields this pleasing search result:
 258
 259 > Did you mean: dacvim
 260
 261 [Cabal]: https://www.haskell.org/cabal/
 262 [Stack]: http://haskellstack.org/
 263 [Vimdoc]: https://github.com/google/vimdoc