]> git.wincent.com - docvim.git/blob - README.md
doc: update brew package name
[docvim.git] / 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 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