Autogenerate stubs and SUMMARY.md in the unstable book by est31 · Pull Request #42612 · rust-lang/rust

est31 · 2017-06-12T20:30:52Z

Removes a speed bump in compiler development by autogenerating stubs for features in the unstable book. See #42454 for discussion.

The PR contains three commits, separated in order to make review easy:

The first commit converts the tidy tool from a binary crate to a crate that contains both a library and a binary. In the second commit, we'll use the tidy library
The second and main commit introduces autogeneration of SUMMARY.md and feature stub files
The third commit turns off the tidy lint that checks for features without a stub, and removes the stub files. A separate commit due to the large number of files touched

Members of the doc team who wish to document some features can either do this (where $rustsrc is the root of the rust repo git checkout):

cd to $rustsrc/src/tools/unstable-book-gen and then do cargo run $rustsrc/src $rustsrc/src/doc/unstable-book to put the stubs into the unstable book
cd to $rustsrc and run git ls-files --others --exclude-standard to list the newly added stubs
choose a file to edit, then git add it and git commit
afterwards, remove all changes by the tool by doing git --reset hard and git clean -f

Or they can do this:

remove the comment marker in src/tools/tidy/src/unstable_book.rs line 122
run ./x.py test src/tools/tidy to list the unstable features which only have stubs
revert the change in 1
document one of the chosen unstable features

The changes done by this PR also allow for further development:

tidy obtains information about tracking issues. We can now forbid differing tracking issues between differing #![unstable] annotations. I haven't done this but plan to in a future PR
we now have a general framework for generating stuff for the unstable book at build time. Further changes can autogenerate a list of the API a given library feature exposes.

The old way to simply click through the documentation after it has been uploaded to rust-lang.org works as well.

r? @nagisa

Fixes#42454

steveklabnik · 2017-06-12T20:38:11Z

/cc @rust-lang/docs @rust-lang/compiler

est31 · 2017-06-12T20:54:33Z

About the stubs removal, I think its better to track stubs outside of git, so that changes of the template affect all of them. Also, the methods listed above only work for stubs tracked outside of git, if you want to add docs for a feature when stubs are inside git you need to open docs one by one and check for stubs. If there is desire to put them into git though, I can put them back!

I have done a new tool instead of adding this to tidy because I think that tidy shouldn't change anything, only read. Also, often you forget to run tidy so the speed bump issue would only be resolved partially, while this runs on every docs run.

nagisa · 2017-06-12T21:01:46Z

Okay, so I’m not sure how the unstable book generated/built/deployed, so I cannot r+ without checking what the people in-the-know say.

All the other changes r=me.

est31 · 2017-06-12T21:06:41Z

how is the unstable book generated/built/deployed

I was assuming it was some form of ./x.py doc. It outputs to build/$TARGET/doc/unstable-book/ and continues to work fine (I've tested ./x.py doc --stage 0).

est31 · 2017-06-13T06:03:26Z

I cannot r+ without checking what the people in-the-know say.

Okay then ... cc @alexcrichton

alexcrichton · 2017-06-13T18:20:46Z

@bors: r=nagisa

build system stuff all looks good to me!

bors · 2017-06-13T18:20:47Z

📌 Commit d0b3afa has been approved by nagisa

Rollup of 6 pull requests - Successful merges: #42408, #42428, #42496, #42597, #42636, #42638 - Failed merges: #42612

bors · 2017-06-14T02:58:04Z

☔ The latest upstream changes (presumably #42644) made this pull request unmergeable. Please resolve the merge conflicts.

Convert tidy into a library so that the data it creates can be used by external tools.

Also, remove stubs.

est31 · 2017-06-14T02:59:50Z

Rebased. re-r? @nagisa

est31 · 2017-06-14T03:00:15Z

@bors p=1 due to hazard of breaking again.

alexcrichton · 2017-06-14T03:23:18Z

@bors: r=nagisa p=1

bors · 2017-06-14T03:23:19Z

📌 Commit e69f908 has been approved by nagisa

bors · 2017-06-14T06:17:47Z

⌛ Testing commit e69f908 with merge 7336555...

bors · 2017-06-14T07:12:25Z

💔 Test failed - status-travis

est31 · 2017-06-14T07:14:35Z

Seems like a legit issue.

[00:47:18] Generating unstable book md files (x86_64-unknown-linux-gnu)
[00:47:18] thread 'main' panicked at 'source "/checkout/obj/build/x86_64-unknown-fuchsia/md-doc/unstable-book" failed to get metadata: No such file or directory (os error 2)', /checkout/src/build_helper/lib.rs:176
[00:47:18] note: Run with `RUST_BACKTRACE=1` for a backtrace.
[00:47:18] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap dist --target x86_64-unknown-fuchsia,aarch64-unknown-fuchsia

I'm investigating...

est31 · 2017-06-14T07:53:35Z

Hmm I couldn't reproduce locally, nor could I get fuchsia working... I have pushed a debug commit (don't merge the PR with that) to try it.

@bors try

bors · 2017-06-14T07:53:45Z

⌛ Trying commit 1173ec8 with merge ae3a043...

@nagisa

Autogenerate stubs and SUMMARY.md in the unstable book Removes a speed bump in compiler development by autogenerating stubs for features in the unstable book. See #42454 for discussion. The PR contains three commits, separated in order to make review easy: * The first commit converts the tidy tool from a binary crate to a crate that contains both a library and a binary. In the second commit, we'll use the tidy library * The second and main commit introduces autogeneration of SUMMARY.md and feature stub files * The third commit turns off the tidy lint that checks for features without a stub, and removes the stub files. A separate commit due to the large number of files touched Members of the doc team who wish to document some features can either do this (where `$rustsrc` is the root of the rust repo git checkout): 1. cd to `$rustsrc/src/tools/unstable-book-gen` and then do `cargo run $rustsrc/src $rustsrc/src/doc/unstable-book` to put the stubs into the unstable book 2. cd to `$rustsrc` and run `git ls-files --others --exclude-standard` to list the newly added stubs 3. choose a file to edit, then `git add` it and `git commit` 4. afterwards, remove all changes by the tool by doing `git --reset hard` and `git clean -f` Or they can do this: 1. remove the comment marker in `src/tools/tidy/src/unstable_book.rs` line 122 2. run `./x.py test src/tools/tidy` to list the unstable features which only have stubs 3. revert the change in 1 3. document one of the chosen unstable features The changes done by this PR also allow for further development: * tidy obtains information about tracking issues. We can now forbid differing tracking issues between differing `#![unstable]` annotations. I haven't done this but plan to in a future PR * we now have a general framework for generating stuff for the unstable book at build time. Further changes can autogenerate a list of the API a given library feature exposes. r? @nagisaFixes#42454

est31 · 2017-06-14T14:14:32Z

Hmm, I've still got to learn how to use bors try...

@bors try

bors · 2017-06-14T14:14:43Z

⌛ Trying commit 9ec3645 with merge f2b20f7...

est31 · 2017-06-15T14:45:44Z

Yeey it works!

est31 · 2017-06-15T14:46:27Z

re-r? @nagisa

nagisa · 2017-06-15T15:10:22Z

@bors r+

bors · 2017-06-15T15:10:23Z

📌 Commit 23bd80a has been approved by nagisa

bors · 2017-06-15T18:28:14Z

⌛ Testing commit 23bd80a with merge 552c58c...

bors · 2017-06-15T19:20:09Z

💔 Test failed - status-travis

Mark-Simulacrum · 2017-06-15T19:28:07Z

Failure looks legitimate.

[00:47:18] Generating unstable book md files (x86_64-unknown-linux-gnu)
[00:47:18] thread 'main' panicked at 'source "/checkout/obj/build/x86_64-unknown-fuchsia/md-doc/unstable-book" failed to get metadata: No such file or directory (os error 2)', /checkout/src/build_helper/lib.rs:176
[00:47:18] note: Run with `RUST_BACKTRACE=1` for a backtrace.
[00:47:18] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap dist --target x86_64-unknown-fuchsia,aarch64-unknown-fuchsia
[00:47:18] Build completed unsuccessfully in 0:46:12

est31 · 2017-06-16T13:08:48Z

Okay. Travis passed now. I've squashed the fix commits. re-r? @nagisa

nagisa · 2017-06-16T13:13:52Z

@bors r+

bors · 2017-06-16T13:13:52Z

📌 Commit b34ac5d has been approved by nagisa

bors · 2017-06-16T14:41:23Z

⌛ Testing commit b34ac5d with merge b40be00...

@nagisa

Autogenerate stubs and SUMMARY.md in the unstable book Removes a speed bump in compiler development by autogenerating stubs for features in the unstable book. See #42454 for discussion. The PR contains three commits, separated in order to make review easy: * The first commit converts the tidy tool from a binary crate to a crate that contains both a library and a binary. In the second commit, we'll use the tidy library * The second and main commit introduces autogeneration of SUMMARY.md and feature stub files * The third commit turns off the tidy lint that checks for features without a stub, and removes the stub files. A separate commit due to the large number of files touched Members of the doc team who wish to document some features can either do this (where `$rustsrc` is the root of the rust repo git checkout): 1. cd to `$rustsrc/src/tools/unstable-book-gen` and then do `cargo run $rustsrc/src $rustsrc/src/doc/unstable-book` to put the stubs into the unstable book 2. cd to `$rustsrc` and run `git ls-files --others --exclude-standard` to list the newly added stubs 3. choose a file to edit, then `git add` it and `git commit` 4. afterwards, remove all changes by the tool by doing `git --reset hard` and `git clean -f` Or they can do this: 1. remove the comment marker in `src/tools/tidy/src/unstable_book.rs` line 122 2. run `./x.py test src/tools/tidy` to list the unstable features which only have stubs 3. revert the change in 1 3. document one of the chosen unstable features The changes done by this PR also allow for further development: * tidy obtains information about tracking issues. We can now forbid differing tracking issues between differing `#![unstable]` annotations. I haven't done this but plan to in a future PR * we now have a general framework for generating stuff for the unstable book at build time. Further changes can autogenerate a list of the API a given library feature exposes. The old way to simply click through the documentation after it has been uploaded to rust-lang.org works as well. r? @nagisaFixes#42454

bors · 2017-06-16T17:05:48Z

☀️ Test successful - status-appveyor, status-travis
Approved by: nagisa
Pushing b40be00 to master...

Its being autogenerated now, as of PR rust-lang#42612. It seems I forgot to remove it.

Remove SUMMARY.md of the unstable book as its autogenerated Its being autogenerated now, as of PR #42612. It seems I forgot to remove it. Also, sort the entries of SUMMARY.md alphabetically.

rust-highfive assigned nagisa Jun 12, 2017

est31 mentioned this pull request Jun 12, 2017
Unstable book is a serious contribution speed bump #42454
Closed

arielb1 added the S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. label Jun 13, 2017

frewsxcv mentioned this pull request Jun 13, 2017
Rollup of 6 pull requests #42644
Merged

bors added a commit that referenced this pull request Jun 14, 2017
Auto merge of#42644- frewsxcv:rollup, r=frewsxcv
e40ef96
Rollup of 6 pull requests - Successful merges: #42408, #42428, #42496, #42597, #42636, #42638 - Failed merges: #42612

Librarify tidy
d810898
Convert tidy into a library so that the data it creates can be used by external tools.

est31 force-pushed the master branch from d0b3afa to e69f908Compare June 14, 2017 02:59

est31 added 2 commits June 14, 2017 04:59

Autogenerate stubs and the summary of the unstable book
c2d5906

Don't require that stubs exist for features in the unstable book
e69f908
Also, remove stubs.

aidanhs removed the S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. label Jun 15, 2017

est31 force-pushed the master branch 4 times, most recently from 71cda1a to b8b4babCompare June 15, 2017 13:22

est31 force-pushed the master branch from b8b4bab to 23bd80aCompare June 15, 2017 14:46

Fix cross compilation
b34ac5d

est31 force-pushed the master branch from 47db4f2 to b34ac5dCompare June 16, 2017 13:08

Mark-Simulacrum mentioned this pull request Jun 16, 2017
Allow setting the limit on std::io::Take. #42697
Merged

bors merged commit b34ac5d into rust-lang:masterJun 16, 2017

Mark-Simulacrum mentioned this pull request Jun 16, 2017
Allocator integration #42313
Merged
10 tasks

est31 mentioned this pull request Jun 16, 2017
Introduce tidy lint to check for inconsistent tracking issues #42705
Merged

est31 mentioned this pull request Jun 17, 2017
Remove SUMMARY.md of the unstable book as its autogenerated #42722
Merged

est31 added a commit to est31/rust that referenced this pull request Jun 18, 2017
Remove SUMMARY.md of the unstable book as its autogenerated
9f6fb8e
Its being autogenerated now, as of PR rust-lang#42612. It seems I forgot to remove it.

Uh oh!

Uh oh!

Conversation

est31 commented Jun 12, 2017• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steveklabnik commented Jun 12, 2017• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

est31 commented Jun 12, 2017• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nagisa commented Jun 12, 2017

Uh oh!

est31 commented Jun 12, 2017

Uh oh!

est31 commented Jun 13, 2017

Uh oh!

alexcrichton commented Jun 13, 2017

Uh oh!

bors commented Jun 13, 2017

Uh oh!

bors commented Jun 14, 2017

Uh oh!

est31 commented Jun 14, 2017

Uh oh!

est31 commented Jun 14, 2017

Uh oh!

alexcrichton commented Jun 14, 2017

Uh oh!

bors commented Jun 14, 2017

Uh oh!

bors commented Jun 14, 2017

Uh oh!

bors commented Jun 14, 2017

Uh oh!

est31 commented Jun 14, 2017

Uh oh!

est31 commented Jun 14, 2017

Uh oh!

bors commented Jun 14, 2017

Uh oh!

est31 commented Jun 14, 2017

Uh oh!

bors commented Jun 14, 2017

Uh oh!

est31 commented Jun 15, 2017

Uh oh!

est31 commented Jun 15, 2017

Uh oh!

nagisa commented Jun 15, 2017

Uh oh!

bors commented Jun 15, 2017

Uh oh!

bors commented Jun 15, 2017

Uh oh!

bors commented Jun 15, 2017

Uh oh!

Mark-Simulacrum commented Jun 15, 2017

Uh oh!

est31 commented Jun 16, 2017

Uh oh!

nagisa commented Jun 16, 2017

Uh oh!

bors commented Jun 16, 2017

Uh oh!

bors commented Jun 16, 2017

Uh oh!

bors commented Jun 16, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

est31 commented Jun 12, 2017•
edited
Loading

steveklabnik commented Jun 12, 2017•
edited
Loading

est31 commented Jun 12, 2017•
edited
Loading