Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom

Determine which files are "essential" automatically #1302

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in 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