You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Explain default behavior of rustdoc in Reference-level explanation
* Flag summary in Guide-level explanation
* Say that crate-info.json is stable because build systems need to rely
on it
* t,s,i -> trait-crate, struct-crate, index-crate
* T, S -> Trait, Struct
@@ -25,109 +25,133 @@ These considerations motivate adding an option for outputting partial CCI (parts
25
25
26
26
# Guide-level explanation
27
27
28
-
In this example, there is a crate `t` which defines a trait `T`, and a crate `s` which defines a struct `S` that implements `T`. Our goal in this demo is for `S` to appear as an implementer in `T`'s docs, even if `s` and `t` are documented independently. This guide will be assuming that we want a crate `i` that serves as our documentation index. See the Unresolved questions section for ideas that do not require an index crate.
28
+
## New flag summary
29
+
30
+
More details are in the Reference-level explanation.
31
+
32
+
*`--parts-out-dir=doc.parts/<crate-name>`: Write information from the current crate to a provided directory.
33
+
*`--include-parts-dir=doc.parts/<crate-name>`: Include cross-crate information from these previously written `doc.parts` directories into a collection that will be written by the current invocation of rustdoc.
34
+
*`--merge=none`: Do not write cross-crate information to the `--out-dir`.
35
+
*`--merge=shared`: Read cross-crate information from the `--out-dir`, and write cross-crate information from the current crate and any crates included via `--include-parts-dir` to the `--out-dir`.
36
+
*`--merge=finalize`: Write cross-crate information from the current crate and any crates included via `--include-parts-dir`, overwriting conflicting files in the `--out-dir`.
37
+
38
+
## Example
39
+
40
+
In this example, there is a crate `trait-crate` which defines a trait `Trait`, and a crate `struct-crate` which defines a struct `Struct` that implements `Trait`. Our goal in this demo is for `Struct` to appear as an implementer in `Trait`'s docs, even if `struct-crate` and `trait-crate` are documented independently. This guide will be assuming that we want a crate `index-crate` that serves as our documentation index. See the Unresolved questions section for ideas that do not require an index crate.
29
41
30
42
```shell
31
-
mkdir -p t/src s/src i/src merged/doc
32
-
echo"pub trait T {}">t/src/lib.rs
33
-
echo"pub struct S; impl t::T for S {}">s/src/lib.rs
echo"pub struct Struct; impl trait-crate::Trait for Struct {}">struct-crate/src/lib.rs
34
46
MERGED=file://$(realpath merged/doc)
35
47
```
36
48
37
-
[Actively use](https://doc.rust-lang.org/rustc/command-line-arguments.html#--extern-specify-where-an-external-library-is-located)`t` and `s` in `i`. The `extern crate` declarations are not needed if the crates are otherwise referenced in the index; intra-doc links are enough.
49
+
[Actively use](https://doc.rust-lang.org/rustc/command-line-arguments.html#--extern-specify-where-an-external-library-is-located)`trait-crate` and `struct-crate` in `index-crate`. The `extern crate` declarations are not needed if the crates are otherwise referenced in the index; intra-doc links are enough.
Link everything with a final invocation of rustdoc on `i`. We will provide `--merge=finalize`, `--include-parts-dir`, and `--include-rendered-docs`. See the Reference-level explanation about these flags.
101
+
Link everything with a final invocation of rustdoc on `index-crate`. We will provide `--merge=finalize`, `--include-parts-dir`, and `--include-rendered-docs`. See the Reference-level explanation about these flags.
Browse `merged/doc/index.html` with cross-crate information.
102
126
103
-
In general, instead of two crates in the environment (`s` and `t`) you could have thousands. Upon any changes, only the index and the crates that are changed have to be re-documented.
127
+
In general, instead of two crates in the environment (`struct-crate` and `trait-crate`) you could have thousands. Upon any changes, only the index and the crates that are changed have to be re-documented.
104
128
105
129
<details>
106
130
<summary>Click here for a directory listing after running the example above.</summary>
107
131
108
132
<pre>
109
133
$ tree . -a
110
134
.
111
-
├── i
135
+
├── index-crate
112
136
│ ├── src
113
137
│ │ └── lib.rs
114
138
│ └── target
115
139
│ └── doc
116
140
│ ├── crates.js
117
141
│ ├── help.html
118
-
│ ├── i
142
+
│ ├── index-crate
119
143
│ │ ├── all.html
120
144
│ │ ├── index.html
121
145
│ │ └── sidebar-items.js
122
146
│ ├── index.html
123
147
│ ├── .lock
124
148
│ ├── search.desc
125
-
│ │ └── i
126
-
│ │ └── i-desc-0-.js
149
+
│ │ └── index-crate
150
+
│ │ └── index-crate-desc-0-.js
127
151
│ ├── search-index.js
128
152
│ ├── settings.html
129
153
│ ├── src
130
-
│ │ └── i
154
+
│ │ └── index-crate
131
155
│ │ └── lib.rs.html
132
156
│ ├── src-files.js
133
157
│ ├── static.files
@@ -145,48 +169,48 @@ $ tree . -a
145
169
│ │ └── unwind_safe
146
170
│ │ ├── trait.RefUnwindSafe.js
147
171
│ │ └── trait.UnwindSafe.js
148
-
│ └── t
149
-
│ └── trait.T.js
172
+
│ └── trait-crate
173
+
│ └── trait.Trait.js
150
174
├── merged
151
175
│ └── doc
152
176
│ ├── crates.js
153
177
│ ├── help.html
154
-
│ ├── i
178
+
│ ├── index-crate
155
179
│ │ ├── all.html
156
180
│ │ ├── index.html
157
181
│ │ └── sidebar-items.js
158
182
│ ├── index.html
159
-
│ ├── s
183
+
│ ├── struct-crate
160
184
│ │ ├── all.html
161
185
│ │ ├── index.html
162
186
│ │ ├── sidebar-items.js
163
-
│ │ └── struct.S.html
187
+
│ │ └── struct.Struct.html
164
188
│ ├── search.desc
165
-
│ │ ├── i
166
-
│ │ │ └── i-desc-0-.js
167
-
│ │ ├── s
168
-
│ │ │ └── s-desc-0-.js
169
-
│ │ └── t
170
-
│ │ └── t-desc-0-.js
189
+
│ │ ├── index-crate
190
+
│ │ │ └── index-crate-desc-0-.js
191
+
│ │ ├── struct-crate
192
+
│ │ │ └── struct-crate-desc-0-.js
193
+
│ │ └── trait-crate
194
+
│ │ └── trait-crate-desc-0-.js
171
195
│ ├── search-index.js
172
196
│ ├── settings.html
173
197
│ ├── src
174
-
│ │ ├── i
198
+
│ │ ├── index-crate
175
199
│ │ │ └── lib.rs.html
176
-
│ │ ├── s
200
+
│ │ ├── struct-crate
177
201
│ │ │ └── lib.rs.html
178
-
│ │ └── t
202
+
│ │ └── trait-crate
179
203
│ │ └── lib.rs.html
180
204
│ ├── src-files.js
181
205
│ ├── static.files
182
206
│ │ ├── COPYRIGHT-23e9bde6c69aea69.txt
183
207
│ │ ├── favicon-2c020d218678b618.svg
184
208
│ │ └── <restofthecontentsexcluded>
185
-
│ ├── t
209
+
│ ├── trait-crate
186
210
│ │ ├── all.html
187
211
│ │ ├── index.html
188
212
│ │ ├── sidebar-items.js
189
-
│ │ └── trait.T.html
213
+
│ │ └── trait.Trait.html
190
214
│ └── trait.impl
191
215
│ ├── core
192
216
│ │ ├── marker
@@ -198,52 +222,52 @@ $ tree . -a
198
222
│ │ └── unwind_safe
199
223
│ │ ├── trait.RefUnwindSafe.js
200
224
│ │ └── trait.UnwindSafe.js
201
-
│ └── t
202
-
│ └── trait.T.js
203
-
├── s
225
+
│ └── trait-crate
226
+
│ └── trait.Trait.js
227
+
├── struct-crate
204
228
│ ├── src
205
229
│ │ └── lib.rs
206
230
│ └── target
207
231
│ ├── doc
208
232
│ │ ├── help.html
209
233
│ │ ├── .lock
210
-
│ │ ├── s
234
+
│ │ ├── struct-crate
211
235
│ │ │ ├── all.html
212
236
│ │ │ ├── index.html
213
237
│ │ │ ├── sidebar-items.js
214
-
│ │ │ └── struct.S.html
238
+
│ │ │ └── struct.Struct.html
215
239
│ │ ├── search.desc
216
-
│ │ │ └── s
217
-
│ │ │ └── s-desc-0-.js
240
+
│ │ │ └── struct-crate
241
+
│ │ │ └── struct-crate-desc-0-.js
218
242
│ │ ├── settings.html
219
243
│ │ └── src
220
-
│ │ └── s
244
+
│ │ └── struct-crate
221
245
│ │ └── lib.rs.html
222
246
│ ├── doc.parts
223
-
│ │ └── s
247
+
│ │ └── struct-crate
224
248
│ │ └── crate-info.json
225
249
│ └── libs.rmeta
226
-
└── t
250
+
└── trait-crate
227
251
├── src
228
252
│ └── lib.rs
229
253
└── target
230
254
├── doc
231
255
│ ├── help.html
232
256
│ ├── .lock
233
257
│ ├── search.desc
234
-
│ │ └── t
235
-
│ │ └── t-desc-0-.js
258
+
│ │ └── trait-crate
259
+
│ │ └── trait-crate-desc-0-.js
236
260
│ ├── settings.html
237
261
│ ├── src
238
-
│ │ └── t
262
+
│ │ └── trait-crate
239
263
│ │ └── lib.rs.html
240
-
│ └── t
264
+
│ └── trait-crate
241
265
│ ├── all.html
242
266
│ ├── index.html
243
267
│ ├── sidebar-items.js
244
-
│ └── trait.T.html
268
+
│ └── trait.Trait.html
245
269
├── doc.parts
246
-
│ └── t
270
+
│ └── trait-crate
247
271
│ └── crate-info.json
248
272
└── libt.rmeta
249
273
</pre>
@@ -280,11 +304,15 @@ When a user documents the final crate, they will provide `--include-parts-dir=<
280
304
281
305
The existing cross-crate information files, like `search-index.js`, all are lists of elements, rendered in an specified way (e.g. as a JavaScript file with a JSON array or an HTML index page containing an unordered list). The current rustdoc (in `write_shared`) pushes the current crate's version of the CCI into the one that is already found in `doc`, and renders a new version. The rest of the proposal uses the term **part** to refer to the pre-merged, pre-rendered element of the CCI. This proposal does not add any new CCI or change their contents (modulo sorting order, whitespace).
282
306
283
-
## New directory: `doc.parts`
307
+
## New directory: `doc.parts/<crate-name>/crate-info.json`
284
308
285
309
`doc.parts` is a directory that holds the partial contents and destination of several cross-crate information files. It only encodes information about a single-crate. This file is written if `--parts-out-dir` is provided. The current crate's information and any `doc.parts` added through `--include-parts-dir` are merged and rendered if `--merge=shared` or `--merge=finalize` are provided.
286
310
287
-
The content of `doc.parts` is unstable. Rustdoc only guarantees that it will accept `doc.parts` files written by the same version of rustdoc, and rustdoc is the only explicitly supported consumer of `doc.parts`. Only the presence of `doc.parts` is stabilized. Non-normatively, there are several pieces of information that `doc.parts` may contain:
311
+
The directory `doc.parts` contains subdirectories for each crate. The crate names are chosen by the caller that invokes rustdoc, and are `--include-parts-dir` and `--parts-out-dir`. These crate names are arbitrary from the perspective of rustdoc, with the constraint that they must be unique. Rustdoc will write a file called `crate-info.json`, whose contents are unstable, to the subdirectory provided to `--parts-out-dir`. Even though the contents of `crate-info.json` are only intended to be consumed by rustdoc, its existence must be stabilized due to the fact that it may be declared to build systems.
312
+
313
+
This directory structure may change with a new edition.
314
+
315
+
Rustdoc only guarantees that it will accept `doc.parts` files written by the same version of rustdoc, and rustdoc is the only explicitly supported consumer of `doc.parts`. Only the presence of `doc.parts`, and its opaque child `crate-info.json`, are stabilized. Non-normatively, there are several pieces of information that `doc.parts` may contain:
288
316
289
317
* Partial source file index for generating `doc/src-files.js`.
290
318
* Partial search index for generating `doc/search-index.js`.
@@ -303,6 +331,8 @@ Crates `--include-parts-dir`ed will not appear in `doc.parts`, as `doc.parts` on
303
331
304
332
If this flag is not provided, no `doc.parts` will be written.
305
333
334
+
The output generated by this flag may be consumed by a future invocation to rustdoc that provides `--include-parts-dir=<path/to>/doc.parts/<crate-name>`.
335
+
306
336
## New flag: `--include-parts-dir=<path/to/doc.parts/crate-name>`
307
337
308
338
If this flag is provided, rustdoc will expect that a previous invocation of rustdoc was made with `--parts-out-dir=<path/to/doc.parts/crate-name>`. It will append the parts from the previous invocation to the ones it will render in the doc root (`--out-dir`). The info that's included is not written to its own `doc.parts`, as `doc.parts` only holds the CCI parts for the current crate.
@@ -323,7 +353,7 @@ When `write_rendered_cci` is active, rustdoc will output the rendered parts to t
323
353
324
354
When `read_rendered_cci` is active, rustdoc will look in the `--out-dir` for rendered cross-crate info files. These files will be used as the base. Any new parts that rustdoc generates with its current invocation and any parts fetched with `include-parts-dir` will be appended to these base files. When it is disabled, the cross-crate info files start empty and are populated with the current crate's info and any crates fetched with `--include-parts-dir`.
325
355
326
-
*`--merge=shared` (`read_rendered_cci && write_rendered_cci`) is the default, and reflects the current behavior of rustdoc.
356
+
*`--merge=shared` (`read_rendered_cci && write_rendered_cci`) is the default, and reflects the current behavior of rustdoc. Rustdoc will look in its `--out-dir` for pre-existing cross-crate information files, and append information to these files from the current crate and any crates referenced through `--include-parts-dir`.
327
357
*`--merge=none` (`!read_rendered_cci && !write_rendered_cci`) means that rustdoc will ignore the cross-crate files in the doc root. Only generate item docs.
328
358
*`--merge=finalize` (`!read_rendered_cci && write_rendered_cci`) outputs crate info based only on the current crate and `--include-parts-dir`'ed crates.
329
359
* A (`read_rendered_cci && !write_rendered_cci`) mode would be useless, since the data that is read would be ignored and not written.
0 commit comments