]> git.wincent.com - docvim.git/blob - README.md
Add a missing type annotation
[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 ## Syntax
35
36 ```vim
37 ""
38 " Docblocks start with a pair of double quotes, followed
39 " by standard Vim comments (with a double quote prefix)
40 " containing Markdown-like text and optional annotations
41 " that look like this:
42 "
43 " ```
44 " @command :Ack {pattern} {options}
45 " ```
46 ```
47
48 ### Supported Markdown features
49
50     # Top-level heading
51
52     ## Sub-heading
53
54     --- (Horizontal dividers)
55
56     > Blockquote
57
58     `inline code`
59
60     ```
61     fenced codeblocks (leading space syntax not supported)
62     ```
63
64     ![alt text](http://example.com/image.jpg)
65     (becomes a link in vimdoc, but an image in markdown)
66
67     - Lists.
68
69 ### Unsupported Markdown syntax
70
71 ```
72 *foo* (emphasis; turns into Vim doc targets instead)
73
74 *,+ (list syntax; just use - instead)
75
76 <html> (we don't want ambiguity with things like <leader> and so on)
77 ```
78
79 ### Annotations
80
81 - `@command`
82 - `@dedent`
83 - `@footer`
84 - `@function`
85 - `@indent`
86 - `@mapping`
87 - `@mappings`
88 - `@option`
89 - `@plugin`
90
91 ## Development
92
93 ### Convenience wrappers
94
95 ```bash
96 bin/accept  # Accept current "golden" test output.
97 bin/docvim  # Run the docvim executable.
98 bin/golden  # Run just the "golden" tests.
99 bin/haddock # Produce Haddock documentation.
100 bin/lint    # Run the linter.
101 bin/tasty   # Run just the Tasty tests.
102 bin/test    # Run all tests, including lints.
103 ```
104
105 These are wrappers for the explicit invocations described below.
106
107 ### Set-up
108
109 You can set-up a development environment using [Stack] (recommended) or [Cabal]:
110
111 ```bash
112 # Stack:
113 brew install haskell-stack
114 stack build
115
116 # Cabal:
117 brew install cabal-install
118 cabal sandbox init
119 cabal install --only-dependencies --enable-tests
120 cabal build
121 ```
122
123 ### Running
124
125 Run using `stack exec` (or `cabal run`) and passing in docvim-specific `OPTIONS`:
126
127 ```bash
128 # Stack:
129 stack exec docvim [OPTIONS]
130
131 # Cabal:
132 cabal run -- [OPTIONS]
133 ```
134
135 You can also run the modules from inside the REPL:
136
137 ```bash
138 # Stack:
139 stack repl
140 > pp "let l:test=1" -- pretty-prints AST
141
142 # Cabal:
143 cabal repl
144 > import Docvim.Parse
145 > pp "let l:test=1" -- pretty-prints AST
146 ```
147
148 ### Building
149
150 ```bash
151 stack build --file-watch
152 ```
153
154 ### Building and viewing the code-level documentation
155
156 ```bash
157 # Stack:
158 stack haddock
159 open .stack-work/dist/x86_64-osx/Cabal-1.22.5.0/doc/html/docvim/index.html
160
161 # Cabal:
162 cabal haddock --executables
163 open dist/doc/html/docvim/docvim/index.html
164 ```
165
166 ### Testing
167
168 ```bash
169 # Stack:
170 stack test        # Runs all test suites, including linting.
171 stack test :tasty # Runs just the Tasty test suite.
172
173 # Cabal:
174 cabal test       # Runs all test suites, including linting.
175 cabal test tasty # Runs just the Tasty test suite.
176 ```
177
178 #### Updating "golden" files
179
180 ```bash
181 # Stack:
182 stack test --test-arguments=--accept          # Runs all test suites.
183 stack test :tasty --test-arguments=--accept   # Runs just the Tasty test suite.
184
185 # Cabal:
186 cabal test --test-options=---accept           # Runs all test suites.
187 cabal test tasty --test-options=---accept     # Runs just the Tasty test suite.
188 ```
189
190 ### Linting
191
192 ```bash
193 # Stack:
194 stack test              # Runs linter as part of overall set of suites.
195 stack test :hlint       # Runs linter alone.
196
197 # Cabal:
198 cabal install hlint     # (First-time only).
199 cabal test              # Runs linter as part of overall set of suites.
200 cabal test hlint        # Runs linter alone.
201
202 hlint src               # If you have HLint installed under $PATH.
203 ```
204
205 ## FAQ
206
207 ### Why a new tool and not an existing one like [Vimdoc]?
208
209 * I wanted to target multiple output formats (Vim help files and Markdown).
210 * I wanted total control over the presentation of the output.
211 * It's fun to build new things from scratch.
212 * The project is a great fit for my learn-me-a-Haskell goal this year.
213
214 ### Why is it called "Docvim"?
215
216 "Vimdoc" was the first name that occurred to me when I started this project, but:
217
218 * The number one hit for "vimdoc" is [this online copy of Vim's own documentation](http://vimdoc.sourceforge.net/).
219 * The name "Vimdoc" is already taken by [a similar project](https://github.com/google/vimdoc).
220
221 So, in a remarkable flash of profound creativity, I settled on "Docvim" instead, which right now yields this pleasing search result:
222
223 > Did you mean: dacvim
224
225 [Cabal]: https://www.haskell.org/cabal/
226 [Stack]: http://haskellstack.org/
227 [Vimdoc]: https://github.com/google/vimdoc