-
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathrustdoc.txt
325 lines (250 loc) · 15 KB
/
rustdoc.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
*rustdoc.txt* Automatic rustdoc management for VIM
____/\\\\\\\\\______________________________________________
__/\\\///////\\\____________________________________________
_\/\\\_____\/\\\__________________________________/\\\______
_\/\\\\\\\\\\\/_____/\\\____/\\\__/\\\\\\\\\\__/\\\\\\\\\\\_
_\/\\\//////\\\____\/\\\___\/\\\_\/\\\//////__\////\\\////__
_\/\\\____\//\\\___\/\\\___\/\\\_\/\\\\\\\\\\____\/\\\______
_\/\\\_____\//\\\__\/\\\___\/\\\_\////////\\\____\/\\\_/\\__
_\/\\\______\//\\\_\//\\\\\\\\\___/\\\\\\\\\\____\//\\\\\___
_\///________\///___\/////////___\//////////______\/////____
__/\\\\\\\\\\\\________________________________
_\/\\\////////\\\______________________________
_\/\\\______\//\\\_____________________________
_\/\\\_______\/\\\_____/\\\\\________/\\\\\\\\_
_\/\\\_______\/\\\___/\\\///\\\____/\\\//////__
_\/\\\_______\/\\\__/\\\__\//\\\__/\\\_________
_\/\\\_______/\\\__\//\\\__/\\\__\//\\\________
_\/\\\\\\\\\\\\/____\///\\\\\/____\///\\\\\\\\_
_\////////////________\/////________\////////__
rustdoc REFERENCE MANUAL
by Adrian Lopez
*rustdoc*
1. Introduction |rustdoc-intro|
2. Commands |rustdoc-commands|
3. Global Settings |rustdoc-settings|
4. Project Settings |rustdoc-project-settings|
=============================================================================
1. Introduction *rustdoc-intro*
vim-rustdoc is a plugin that takes care of the management of rustdoc
documentation in Vim. It will (re)generate rustdoc documentation as you work
while staying completely out of your way.
In order to generate documentation, rustdoc will have to figure out what's in
your project. To do this, it will locate well-known project root markers like
SCM folders (.git, .hg, etc.), any custom markers you define (with
|rustdoc_project_root|).
=============================================================================
2. Commands *rustdoc-commands*
*rustdoc-project-commands*
The following commands are only available in buffers that have been found to
belong to a project that should be managed by rustdoc. See
|rustdoc_project_root| for how rustdoc figures out the project a file
belongs to. When no project is found (i.e. the file is not under any of the
known project markers), rustdoc is disabled for that buffer, and the
following commands and remarks don't apply.
If you want to force-disable rustdoc for a given project even though it does
match one of the items in |rustdoc_project_root|, create a file named
"`.norustdoc`" at the root of the project.
*:rustdocRegen*
:RustdocRegen
Manually (re)generate the rustdoc documentation.
This can be useful when |rustdoc_auto_regen| is set to
0.
Some debugging/troubleshooting commands are also available if the
|rustdoc_define_advanced_commands| global setting is set to 1.
:RustdocOpen
Opens the documentation file on the browser. Both the
file and the browser can be customized with
|rustdoc_browser_file| and |rustdoc_browser_cmd|.
Some debugging/troubleshooting commands are also available if the
|rustdoc_define_advanced_commands| global setting is set to 1.
*:rustdocToggleEnabled*
:RustdocToggleEnabled
Disables and re-enables rustdoc.
When rustdoc is disabled, it won't (re)generate
rustdoc when you save a buffer. It will however still
look for project markers as you open new buffers so
that they can start working again when you re-enable
rustdoc.
{only available when
|rustdoc_define_advanced_commands| is set}
*rustdocToggleTrace*
:RustdocToggleTrace
If you want to keep an eye on what rustdoc is doing,
you can enable tracing. This will show messages every
time rustdoc does something. It can get annoying
quickly, since it will require you to press a key to
dismiss those messages, but it can be useful to
troubleshoot a problem.
{only available when
|rustdoc_define_advanced_commands| is set}
=============================================================================
3. Global Settings *rustdoc-settings*
The following settings can be defined in your |vimrc| to change the default
behaviour of rustdoc.
*rustdoc_enabled*
g:rustdoc_enabled
Defines whether rustdoc should be enabled. When
disabled, rustdoc will still scan for project root
markers when opening buffers. This is so that when you
re-enable rustdoc, you won't have some buffers
mysteriously working while others (those open last)
don't.
Defaults to `1`.
*rustdoc_trace*
g:rustdoc_trace
When true, rustdoc will spit out debugging
information as Vim messages (which you can later read
with |:messages|).
Defaults to `0`.
*rustdoc_project_root*
g:rustdoc_project_root
When a buffer is loaded, rustdoc will figure out if
it's part of a project that should have rustdoc managed
automatically. To do this, it looks for "root markers"
in the current file's directory and its parent
directories. If it finds any of those markers,
rustdoc will be enabled for the project. This is
important because by default, this plugin will use the
project's root directory to run rustdoc.
The default markers are:
`['.git', '.hg', '.svn', '.bzr', '_darcs', '_darcs', '_FOSSIL_', '.fslckout']`
*rustdoc_include_filetypes*
g:rustdoc_include_filetypes
A |List| of file types (see |'filetype'|) that rustdoc
should use. When a buffer is opened, if its
'filetype' is found in this list, rustdoc features
will be available for this buffer.
Defaults to rustdoc officially supported languages:
(`['rust']`).
*rustdoc_exclude_project_root*
g:rustdoc_exclude_project_root
A list of project roots to generally ignore. If a file
is opened inside one of those projects, rustdoc
won't be activated. This is similar to placing
a `.norustdoc` file in the root of those projects, but
can be useful when you don't want to, or can't, place
such a file there.
Defaults to `['/usr/local', '/opt/homebrew', '/home/linuxbrew/.linuxbrew']`,
which are the folders where Homebrew is known to
create a Git repository by default.
*rustdoc_project_root_finder*
g:rustdoc_project_root_finder
When a buffer is loaded, rustdoc uses a default
(internal) implementation to find that file's
project's root directory, using settings like
|g:rustdoc_project_root|. When you specify
|g:rustdoc_project_root_finder|, you can tell
rustdoc to use a custom implementation, such as
`vim-projectroot`. The value of this setting must be
the name of a function that takes a single string
argument (the path to the current buffer's file) and
returns a string value (the project's root directory).
Defaults to `''`.
Note: when set, the called implementation will
possibly ignore |g:rustdoc_project_root|.
Note: an implementation can fallback to the default
behaviour by calling
`rustdoc#default_get_project_root`.
*rustdoc_generate_on_new*
g:rustdoc_generate_on_new
If set to 1, rustdoc will start generating the docs
when a new project is open. A new project is
considered open when a buffer is created for a file
that has not been "seen" yet
in the current Vim session -- which pretty much means
when you open the first file in a given source control
repository.
When set to 0, rustdoc won't do anything special.
Defaults to 1.
*rustdoc_generate_on_write*
g:rustdoc_generate_on_write
If set to 1, rustdoc will (re)generate rustdoc
documentation when a file inside that project is
saved. See |rustdoc_project_root| for how rustdoc
locates the project.
When set to 0, rustdoc won't do anything on save.
This means that the docs won't reflect
the latest changes, and you will have to run
|rustdocUpdate| manually.
Defaults to 1.
*rustdoc_generate_on_empty_buffer*
g:rustdoc_generate_on_empty_buffer
If set to 1, rustdoc will start generating the rustdoc
documentation even if there's no buffer currently open,
as long as the current working directory (as returned by
|:cd|) is inside a known project.
This is useful if you want rustdoc to generate the
docs right after opening Vim.
Defaults to 0.
*rustdoc_resolve_symlinks*
g:rustdoc_resolve_symlinks
When set to 1, rustdoc will resolve any symlinks in
the current buffer's path in order to find the project
it belongs to. This is what you want if you're editing
a symlink located outside of the project, and it
points to a file inside the project. However, this is
maybe not what you want if the symlink itself is
part of the project.
Defaults to 0.
*rustdoc_init_user_func*
g:rustdoc_init_user_func
When set to a non-empty string, it is expected to be
the name of a function that will be called when a file
is opened in a project. The function gets passed the
path of the file and if it returns 0, rustdoc won't
be enabled for that file.
You can use this to manually set buffer-local
settings:
Defaults to "".
*rustdoc_define_advanced_commands*
g:rustdoc_define_advanced_commands
Defines some advanced commands like
|rustdocToggleEnabled|.
*rustdoc_auto_regen*
g:rustdoc_auto_regen
When setted to 1, rustdoc will automatically generate
the documentation for you.
If you prefer to generate the docs manually, you can
use the command |rustdocRegen|. In this case you might want
to set this this global to 0.
Defaults to 1.
*rustdoc_cmd*
g:rustdoc_cmd
This is the command that rustdoc uses to generate the
project documentation.
Please, take the default value of this global as reference.
Defaults to "rustdoc".
*rustdoc_browser_cmd*
g:rustdoc_browser_cmd
It is the program that will be used to open
|rustdoc_browser_file|.
This can be your internet browser, or anything else,
really.
Defaults to "xdg-open".
*rustdoc_browser_file*
g:rustdoc_browser_file
The file that will be opened by the command
|rustdocOpen|.
Defaults to "./docs/index.html".
*rustdoc_verbose_manual_regen*
g:rustdoc_verbose_manual_regen
Display a message on the status bar when rustdoc is
manually regenerated using the command :|rustdocRegen|.
Normally, used through a keybinding.
Defaults to "1".
*rustdoc_verbose_open*
g:rustdoc_verbose_open
Display a message on the status bar when the rustdoc
documentation is opened on the browser using the
command :|rustdocOpen|. Normally, used
through a keybinding.
Defaults to "1".
=============================================================================
4. Project Settings *rustdoc-project-settings*
rustdoc can be customized to some extent on a per-project basis with the
following files present in the project root directory:
*rustdoc-.norustdoc*
`.norustdoc`: if this file exists, rustdoc will be disabled completely for that
project.
vim:tw=78:et:ft=help:norl: