README.md

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