Skip to content

Determine which files are "essential" automatically #1302

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Jump to bottom
Closed
jyn514 opened this issue Mar 5, 2021 · 10 comments · Fixed by #1312
Closed

Determine which files are "essential" automatically #1302

jyn514 opened this issue Mar 5, 2021 · 10 comments · Fixed by #1312
Assignees
@jyn514
Labels
A-builds Area: Building the documentation for a crate

Comments

@jyn514
Copy link
Member

jyn514 commented Mar 5, 2021

Rustdoc occasionally adds or removes generated files. This often leads to breakage like #1300, and is a pain to update manually. It would be better to determine automatically which files are essential so that docs.rs doesn't have to be updated whenever rustdoc changes.
@jyn514 jyn514 added the A-builds Area: Building the documentation for a crate label Mar 5, 2021
@jyn514
Copy link
Member Author

jyn514 commented Mar 5, 2021

cc rust-lang/rust#80705, rust-lang/rust#82732

@GuillaumeGomez
Copy link
Member

How do you propose to do that?

@jyn514
Copy link
Member Author

jyn514 commented Mar 5, 2021

Rustdoc only adds the resource-suffix to essential files. We can copy all files containing the resource suffix.

$ rustdoc -Z unstable-options --resource-suffix=-xxx example.rs 
$ ls doc/*-xxx*
doc/ayu-xxx.css    doc/down-arrow-xxx.svg     doc/light-xxx.css      doc/rustdoc-xxx.css      doc/settings-xxx.js       doc/theme-xxx.js
doc/brush-xxx.svg  doc/favicon-16x16-xxx.png  doc/main-xxx.js        doc/rust-logo-xxx.png    doc/source-files-xxx.js   doc/wheel-xxx.svg
doc/crates-xxx.js  doc/favicon-32x32-xxx.png  doc/normalize-xxx.css  doc/search-index-xxx.js  doc/source-script-xxx.js
doc/dark-xxx.css   doc/favicon-xxx.svg        doc/noscript-xxx.css   doc/settings-xxx.css     doc/storage-xxx.js

@jyn514
Copy link
Member Author

jyn514 commented Mar 5, 2021

Hmm, that only works for versioned files, though. I don't know if there's a way to do it for unversioned files.

@jyn514
Copy link
Member Author

jyn514 commented Mar 5, 2021

@GuillaumeGomez could we add a --print=unversioned-files or something to rustdoc?

@GuillaumeGomez
Copy link
Member

We could add an option to rustdoc which would list such files. The big question will be: how to do it so that the essential files are always in there without requiring manual changes from rustdoc side every time.

@jyn514
Copy link
Member Author

jyn514 commented Mar 5, 2021

We could add an option to rustdoc which would list such files. The big question will be: how to do it so that the essential files are always in there without requiring manual changes from rustdoc side every time.

Oh that bit's not hard, I have a PR that's half working. Will send it out shortly.

@GuillaumeGomez
Copy link
Member

Awesome! (Just confess: you created this issue to show off right? 😝 )

@jyn514
Copy link
Member Author

jyn514 commented Mar 5, 2021

Just confess: you created this issue to show off right?

Actually I thought of the idea soon after you asked 😆 it was helpful to bounce ideas :)

@GuillaumeGomez
Copy link
Member

It was haha.

@jyn514 jyn514 self-assigned this Mar 5, 2021
This was referenced Mar 5, 2021
Merged
Merged
Merged
JohnTitor added a commit to JohnTitor/rust that referenced this issue Mar 6, 2021
@JohnTitor
Rollup merge of rust-lang#82803 - jyn514:unversioned-files, r=Guillau…
8c591b8 
…meGomez

rustdoc: Add an unstable option to print all unversioned files

This allows sharing those files between different doc invocations
without having to know their names ahead of time.

Helps with rust-lang/docs.rs#1302.
r? `@GuillaumeGomez` cc `@pietroalbini` `@Nemo157`
JohnTitor added a commit to JohnTitor/rust that referenced this issue Mar 6, 2021
@JohnTitor
Rollup merge of rust-lang#82803 - jyn514:unversioned-files, r=Guillau…
85796e0 
…meGomez

rustdoc: Add an unstable option to print all unversioned files

This allows sharing those files between different doc invocations
without having to know their names ahead of time.

Helps with rust-lang/docs.rs#1302.
r? ``@GuillaumeGomez`` cc ``@pietroalbini`` ``@Nemo157``
m-ou-se added a commit to m-ou-se/rust that referenced this issue Mar 6, 2021
@m-ou-se
Rollup merge of rust-lang#82803 - jyn514:unversioned-files, r=Guillau…
b4224fe 
…meGomez

rustdoc: Add an unstable option to print all unversioned files

This allows sharing those files between different doc invocations
without having to know their names ahead of time.

Helps with rust-lang/docs.rs#1302.
r? ```@GuillaumeGomez``` cc ```@pietroalbini``` ```@Nemo157```
JohnTitor added a commit to JohnTitor/rust that referenced this issue Mar 7, 2021
@JohnTitor
Rollup merge of rust-lang#82803 - jyn514:unversioned-files, r=Guillau…
379679b 
…meGomez

rustdoc: Add an unstable option to print all unversioned files

This allows sharing those files between different doc invocations
without having to know their names ahead of time.

Helps with rust-lang/docs.rs#1302.
r? ````@GuillaumeGomez```` cc ````@pietroalbini```` ````@Nemo157````
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue Mar 9, 2021
@Dylan-DPC
Rollup merge of rust-lang#82802 - jyn514:build-rustdoc-fullmake, r=Ma…
16e14ce 
…rk-Simulacrum

Build rustdoc for run-make tests, not just run-make-fulldeps

Rustdoc almost never needs a full stage 2 compiler, and requiring
rustdoc tests to be in run-make-fulldeps adds a lot of compile time for
no reason.

This is the same change from rust-lang#81197, but separated into its own PR. I ran into this again today while working on rust-lang/docs.rs#1302.
r? `@Mark-Simulacrum`
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue Mar 9, 2021
@Dylan-DPC
Rollup merge of rust-lang#82802 - jyn514:build-rustdoc-fullmake, r=Ma…
d8c4e2d 
…rk-Simulacrum

Build rustdoc for run-make tests, not just run-make-fulldeps

Rustdoc almost never needs a full stage 2 compiler, and requiring
rustdoc tests to be in run-make-fulldeps adds a lot of compile time for
no reason.

This is the same change from rust-lang#81197, but separated into its own PR. I ran into this again today while working on rust-lang/docs.rs#1302.
r? ``@Mark-Simulacrum``
JohnTitor added a commit to JohnTitor/rust that referenced this issue Mar 9, 2021
@JohnTitor
Rollup merge of rust-lang#82802 - jyn514:build-rustdoc-fullmake, r=Ma…
48a393e 
…rk-Simulacrum

Build rustdoc for run-make tests, not just run-make-fulldeps

Rustdoc almost never needs a full stage 2 compiler, and requiring
rustdoc tests to be in run-make-fulldeps adds a lot of compile time for
no reason.

This is the same change from rust-lang#81197, but separated into its own PR. I ran into this again today while working on rust-lang/docs.rs#1302.
r? ```@Mark-Simulacrum```
@jyn514 jyn514 mentioned this issue Mar 10, 2021
Merged
@GuillaumeGomez GuillaumeGomez mentioned this issue Mar 10, 2021
Merged
This was referenced Mar 23, 2021
Closed
Closed
# for free to join this conversation on GitHub. Already have an account? # to comment
Assignees

@jyn514 jyn514

Labels
A-builds Area: Building the documentation for a crate
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Don't hard-code essential rustdoc files jyn514/docs.rs
2 participants
@GuillaumeGomez @jyn514