]> git.wincent.com - docvim.git/blob - README.md
Squelch warning
[docvim.git] / 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