-
Notifications
You must be signed in to change notification settings - Fork 3.4k
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.
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
Extract code and output; script formatting and updating them #2231
Merged
Merged
Changes from all commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
7a9c8f4
Set cargo new config vars to placeholders for example projects
carols10cents 8b0c216
Script to generate release artifact of just the listings
carols10cents 6579c05
Include code without hidden lines for nostarch files
carols10cents 7945e10
Document administrative tasks that are now scripted
carols10cents 5c71aac
Extract code listings to separate files
carols10cents bc8c9f1
Write a script to update output with a new version of rustc
carols10cents dec27ee
Add rustfmt to the update-rustc script
carols10cents fd3e920
Commit the changes that rustfmt made to all the listings
carols10cents 3648956
Rustfmt our tools too
carols10cents 5f4f738
Update to Rust 1.38
carols10cents 3c34849
Update to Rust 1.39
carols10cents c642b72
Update to Rust 1.40
carols10cents File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
[cargo-new] | ||
name = "Your Name" | ||
email = "you@example.com" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,7 +3,7 @@ dist: trusty | |
language: rust | ||
cache: cargo | ||
rust: | ||
- 1.37.0 | ||
- 1.40.0 | ||
branches: | ||
only: | ||
- master | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,109 @@ | ||
# Administrative Tasks | ||
|
||
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 | ||
|
||
- Change the version number in `.travis.yml` | ||
- Change the version number in `rust-toolchain`, which should change the version you're using | ||
locally with `rustup` | ||
- Change the version number in `src/title-page.md` | ||
- Run `./tools/update-rustc.sh` (see its commented code for details on what it does) | ||
- Inspect the changes (by looking at the files changed according to git) and their effects (by | ||
looking at the files in `tmp/book-before` and `tmp/book-after`) and commit them if they look good | ||
- Grep for `manual-regeneration` and follow the instructions in those places to update output that | ||
cannot be generated by a script | ||
|
||
## Release a new version of the listings | ||
|
||
We now make `.tar` files of complete projects containing every listing available [as GitHub | ||
Releases](https://github.com/rust-lang/book/releases). To create a new release artifact, for | ||
example if there have been code changes due to edits or due to updating Rust and `rustfmt`, do the | ||
following: | ||
|
||
- Create a git tag for the release and push it to GitHub, or create a new tag by going to the | ||
GitHub UI, [drafting a new release](https://github.com/rust-lang/book/releases/new), and entering | ||
a new tag instead of selecting an existing tag | ||
- Run `cargo run --bin release_listings`, which will generate `tmp/listings.tar.gz` | ||
- Upload `tmp/listings.tar.gz` in the GitHub UI for the draft release | ||
- Publish the release | ||
|
||
## Add a new listing | ||
|
||
To facilitate the scripts that run `rustfmt` on all the listings, update the output when the | ||
compiler is updated, and produce release artifacts containing full projects for the listings, any | ||
listing beyond the most trivial should be extracted into a file. To do that: | ||
|
||
- Find where the new listing should go in the `listings` directory. | ||
- There is one subdirectory for each chapter | ||
- Numbered listings should use `listing-[chapter num]-[listing num]` for their directory names. | ||
- Listings without a number should start with `no-listing-` followed by a number that indicates | ||
its position in the chapter relative to the other listings without numbers in the chapter, then | ||
a short description that someone could read to find the code they're looking for. | ||
- Listings used only for displaying the output of the code (for example, when we say "if we had | ||
written x instead of y, we would get this compiler error:" but we don't actually show code x) | ||
should be named with `output-only-` followed by a number that indicates its position in the | ||
chapter relative to the other listings used only for output, then a short description that | ||
authors or contributors could read to find the code they're looking for. | ||
- **Remember to adjust surrounding listing numbers as appropriate!** | ||
- Create a full Cargo project in that directory, either by using `cargo new` or copying another | ||
listing as a starting point. | ||
- Add the code and any surrounding code needed to create a full working example. | ||
- If you only want to show part of the code in the file, use anchor comments (`// ANCHOR: some_tag` | ||
and `// ANCHOR_END: some_tag`) to mark the parts of the file you want to show. | ||
- For Rust code, use the `{{#rustdoc_include [fileame:some_tag]}}` directive within the code blocks | ||
in the text. The `rustdoc_include` directive gives the code that doesn't get displayed to | ||
`rustdoc` for `mdbook test` purposes. | ||
- For anything else, use the `{{#include [filename:some_tag]}}` directive. | ||
- If you want to display the output of a command in the text as well, create an `output.txt` file | ||
in the listing's directory as follows: | ||
- Run the command, like `cargo run` or `cargo test`, and copy all of the output. | ||
- Create a new `output.txt` file with the first line `$ [the command you ran]`. | ||
- Paste the output you just copied. | ||
- Run `./tools/update-rustc.sh`, which should perform some normalization on the compiler output. | ||
- Include the output in the text with the `{{#include [filename]}}` directive. | ||
- Add and commit output.txt. | ||
- If you want to display output but for some reason it can't be generated by a script (say, because | ||
of user input or external events like making a web request), keep the output inline but make a | ||
comment that contains `manual-regeneration` and instructions for manually updating the inline | ||
output. | ||
- If you don't want this example to even be attempted to be formatted by `rustfmt` (for example | ||
because the example doesn't parse on purpose), add a `rustfmt-ignore` file in the listing's | ||
directory and the reason it's not being formatted as the contents of that file (in case it's a | ||
rustfmt bug that might get fixed someday). | ||
|
||
## See the effect of some change on the rendered book | ||
|
||
To check, say, updating `mdbook` or changing the way files get included: | ||
|
||
- Generate a built book before the change you want to test by running `mdbook build -d | ||
tmp/book-before` | ||
- Apply the changes you want to test and run `mdbook build -d tmp/book-after` | ||
- Run `./tools/megadiff.sh` | ||
- Files remaining in `tmp/book-before` and `tmp/book-after` have differences you can manually | ||
inspect with your favorite diff viewing mechanism | ||
|
||
## Produce new markdown files for No Starch | ||
|
||
- Run `./tools/nostarch.sh` | ||
- Spot check the files that script created in the `nostarch` directory | ||
- Check them into git if you're starting a round of edits | ||
|
||
## Produce markdown from docx for diffing | ||
|
||
- TODO Carol to document this next time she does it | ||
|
||
## Generate Graphviz dot | ||
|
||
We're using [Graphviz](http://graphviz.org/) for some of the diagrams in the | ||
book. The source for those files live in the `dot` directory. To turn a `dot` | ||
file, for example, `dot/trpl04-01.dot` into an `svg`, run: | ||
|
||
```bash | ||
$ dot dot/trpl04-01.dot -Tsvg > src/img/trpl04-01.svg | ||
``` | ||
|
||
In the generated SVG, remove the width and the height attributes from the `svg` | ||
element and set the `viewBox` attribute to `0.00 0.00 1000.00 1000.00` or other | ||
values that don't cut off the image. |
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
6 changes: 6 additions & 0 deletions
6
listings/ch02-guessing-game-tutorial/listing-02-01/Cargo.lock
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
9 changes: 9 additions & 0 deletions
9
listings/ch02-guessing-game-tutorial/listing-02-01/Cargo.toml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
[package] | ||
name = "guessing_game" | ||
version = "0.1.0" | ||
authors = ["Your Name <you@example.com>"] | ||
edition = "2018" | ||
|
||
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html | ||
|
||
[dependencies] |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
😍