Extract code and output; script formatting and updating them #2231

carols10cents · 2020-01-24T21:47:39Z

This PR replaces #1949; I think I've organized the changed so be easier to review, slightly.

I would recommend going commit-by-commit to review this and skipping some commits.

I'm also happy to make a separate branch with the generated book committed before and after these changes to show the effect they have, if that's something you're interested in reviewing (I've looked at that locally).

I've tried to document how to use the tools I've added here in ADMIN_TASKS.md, I would especially like to know if that is clear.

In the release_listings and update-rustc.sh tools themselves, I've tried to add comments describing my intentions for what these tools do. I'd love to know if that's clear, and if you have any ideas on improving them.

The advantages of this PR are:

We can easily generate release artifacts that contain full projects for each listing, and keep them in sync with what appears inline, making it easier for readers to follow along
We can automatically update compiler errors for new Rust versions all at once to be less confusing for readers using newer compiler versions
We can format all the listings with rustfmt to be demonstrating good style

The disadvantages are:

It's harder to edit the code and text because they're not in the same file anymore (but we aren't doing large edits at this point anyway)
A whole lot of PRs are going to have merge conflicts (I'll fix them)

I'm going to add some more commits to this branch in a minute demonstrating the rust updating, but I wanted to get CI running on this version.

@steveklabnik please let me know if I can do anything to make reviewing this easier!

With a mechanism to ignore particular listings for various reasons

steveklabnik · 2020-01-27T13:50:23Z

ADMIN_TASKS.md

+This documentation is for Carol and Steve and anyone else managing the repo to remember how to do
+occasional maintenance tasks.
+
+## Update the `rustc` version


steveklabnik

This is amazing! Thanks for all the hard work here. I have one question, but this is good to go as far as I'm concerned :)

tools/update-rustc.sh

steveklabnik · 2020-01-27T13:54:18Z

listings/ch04-understanding-ownership/listing-04-01/rustfmt-ignore

@@ -0,0 +1,3 @@
+We have some weird comments pointing out borrowing scopes that we don't want to change;
+unfortunately I haven't found a way to skip them with rustfmt that works so for now we're going to
+manually skip those listings. See: https://github.com/rust-lang/rustfmt/issues/4028


ah this is very interesting... this seems good to be honest.

carols10cents · 2020-01-27T13:58:22Z

Thank you steve!!!!!!

kidwm · 2020-02-06T04:07:15Z

@carols10cents BTW, also have to update the Requirements section of README.md, since rustdoc_include needs mdBook >= 0.3.2

Update books. This required some changes in how the books are tested due to some changes in rust-lang/book. It uses new syntax that is not compatible with bare `rustdoc --test`. This changes it so that it uses rustbook to run the tests, which is essentially the same as `mdbook test`. ## reference 7 commits in 11e893f..64239df 2020-01-18 21:24:08 +0100 to 2020-02-10 19:05:13 +0100 - Update for nested receivers. (rust-lang/reference#724) - clarify note re. leading `::` in 2018 (rust-lang/reference#752) - Update macro-ambiguity.md (rust-lang/reference#754) - typo fix: add missing `by` (rust-lang/reference#753) - fix `TypeParamBounds` link on trait objects (rust-lang/reference#749) - reorganize docs on references (rust-lang/reference#745) - add MacroRepOp usage for ? (rust-lang/reference#744) ## book 49 commits in 87dd6843678575f8dda962f239d14ef4be14b352..6fb3705e5230311b096d47f7e2c91f9ce24393d0 2020-01-20 15:20:40 -0500 to 2020-02-12 13:48:57 -0500 - Fix nomicon links. (rust-lang/book#2253) - Update to Rust 1.41.0 (rust-lang/book#2244) - Listing 19-6: use ptr.add instead of ptr.offset (rust-lang/book#2201) - Remove unneeded mutable reference - Clarify deref coercion explanation - Fix typo in link to 1.30 book - Acknowledge Murphy's Law - Clarify that buffer overread is UB in C - Change from "must" to "idiomatic" about comments - Fancy quotes - Make HashMap types match previous example; add fwd ref to ch 13 - Tweak wording to array clarification - Merge remote-tracking branch 'origin/pr/2236' - Update all our crates (rust-lang/book#2235) - Reword git caveat - Merge remote-tracking branch 'origin/pr/2234' - Merge remote-tracking branch 'origin/pr/2230' - println! is a macro (rust-lang/book#2224) - Update a translated version link (rust-lang/book#2221) - move `Macro invocation` from section on tuple to section on mac… (rust-lang/book#2206) - Do not limit `Self` usage in trait implementation (rust-lang/book#2197) - Merge remote-tracking branch 'origin/pr/2191' - Fix wrapping - Merge remote-tracking branch 'origin/pr/2187' - Updated appendix 07 to reflect deprecation of rustup install (rust-lang/book#2181) - Make links to the Nomicon consistent - Merge remote-tracking branch 'origin/pr/2180' - Merge remote-tracking branch 'origin/pr/2175' - Merge remote-tracking branch 'origin/pr/2171' - Merge remote-tracking branch 'origin/pr/2170' - Clarify and make consistent the explanation of unions - Merge remote-tracking branch 'origin/pr/2166' - Handle dev or test in the Finished output line - Link to macros by example rather than macros (rust-lang/book#2164) - Merge remote-tracking branch 'origin/pr/2147' - Fix parens (rust-lang/book#2132) - Clarify type inference with closures requires calling the closures - Update link to French translation (rust-lang/book#2119) - Merge remote-tracking branch 'origin/pr/2108' - Add an explicit cross reference to data type - Merge remote-tracking branch 'origin/pr/2105' - ch15-02-deref: Improve explanation on immut-to-mut (rust-lang/book#2030) - Remove unnecessary quotes - Make markdown link identifier match - Remove extra newline - Merge remote-tracking branch 'origin/pr/2004' - Extract code and output; script formatting and updating them (rust-lang/book#2231) - Switch "Finally" to "Next" to reflect new chapters having been… (rust-lang/book#2098) - ch19-06 added curly braces to macro output (rust-lang/book#2050) ## rust-by-example 2 commits in 1c2bd024d13f8011307e13386cf1fea2180352b5..32facd5522ddbbf37baf01e4e4b6562bc55c071a 2020-01-20 12:18:36 -0300 to 2020-02-11 09:25:06 -0300 - Add missing `dyn` in code sample (rust-lang/rust-by-example#1306) - Improve grammar in a few sections (rust-lang/rust-by-example#1305) ## edition-guide 1 commits in 1a2390247ad6d08160e0dd74f40a01a9578659c2..37f9e6848411188a1062ead1bd8ebe4b8aa16899 2019-12-29 10:40:55 -0800 to 2020-02-10 14:36:14 +0100 - Fixed typo (rust-lang/edition-guide#196) ## embedded-book 4 commits in 4d78994915af1bde9a95c04a8c27d8dca066232a..b2e1092bf67bd4d7686c4553f186edbb7f5f92db 2020-01-14 08:25:25 +0000 to 2020-01-30 08:45:46 +0000 - Make typestate initialization notes correct (rust-embedded/book#224) - Mention discovery book more prominently (rust-embedded/book#219) - Replace nursery links with rust-lang links (rust-embedded/book#222) - Add a Glossary appendix page (rust-embedded/book#223)

carols10cents added 4 commits January 20, 2020 15:39

Set cargo new config vars to placeholders for example projects

7a9c8f4

Script to generate release artifact of just the listings

8b0c216

Include code without hidden lines for nostarch files

6579c05

Document administrative tasks that are now scripted

7945e10

carols10cents requested a review from steveklabnik January 24, 2020 21:47

carols10cents force-pushed the extract-files-squashed branch 3 times, most recently from 2bbef53 to 66ab8d8 Compare January 26, 2020 01:56

carols10cents added 8 commits January 25, 2020 21:20

Extract code listings to separate files

5c71aac

Write a script to update output with a new version of rustc

bc8c9f1

Add rustfmt to the update-rustc script

dec27ee

With a mechanism to ignore particular listings for various reasons

Commit the changes that rustfmt made to all the listings

fd3e920

Rustfmt our tools too

3648956

Update to Rust 1.38

5f4f738

Update to Rust 1.39

3c34849

Update to Rust 1.40

c642b72

carols10cents force-pushed the extract-files-squashed branch from 66ab8d8 to c642b72 Compare January 26, 2020 02:21

steveklabnik reviewed Jan 27, 2020

View reviewed changes

steveklabnik approved these changes Jan 27, 2020

View reviewed changes

carols10cents merged commit e4b326f into master Jan 27, 2020

carols10cents deleted the extract-files-squashed branch January 27, 2020 13:58

ehuss mentioned this pull request Feb 12, 2020

Update books. rust-lang/rust#69115

Merged

newca12 mentioned this pull request Sep 21, 2020

A policy is required regarding rust toolchain and error messages #2459

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Extract code and output; script formatting and updating them #2231

Extract code and output; script formatting and updating them #2231

carols10cents commented Jan 24, 2020 •

edited

Loading

steveklabnik Jan 27, 2020

steveklabnik left a comment

steveklabnik Jan 27, 2020

carols10cents commented Jan 27, 2020

kidwm commented Feb 6, 2020 •

edited

Loading

Extract code and output; script formatting and updating them #2231

Extract code and output; script formatting and updating them #2231

Conversation

carols10cents commented Jan 24, 2020 • edited Loading

steveklabnik Jan 27, 2020

Choose a reason for hiding this comment

steveklabnik left a comment

Choose a reason for hiding this comment

steveklabnik Jan 27, 2020

Choose a reason for hiding this comment

carols10cents commented Jan 27, 2020

kidwm commented Feb 6, 2020 • edited Loading

carols10cents commented Jan 24, 2020 •

edited

Loading

kidwm commented Feb 6, 2020 •

edited

Loading