Async chapter edits #3983
Merged
Async chapter edits #3983
Conversation
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
A number of examples *already* do not work correctly, and the inbound async chapter requires Rust 2021.
Use Rust 2021 Edition for mdBook
- `tests` -> `src/tests/mod.rs` - `tests::config` -> `src/tests/config.rs` This is just profoundly easier to work with.
When I originally built this, I thought *all* “listings” had numbers and captions, but it turns out that there are a number of places in the book where having the overall `figure`-driven output, i.e. with a file name, is desirable even though there is no number or caption. A potential enhancement later would be to require a caption if a number is present, since that seems to be what the book actually does.
XML does not allow more XML to appear in the body of an attribute, but this is not XML! It is *HTML*, since Markdown allows embedding HTML, and HTML *does* allow embedding further `<` and `>` characters within the attributes on the element. Accordingly, switch to `html_parser`, add a test covering this behavior, and update `ListingBuilder` to take the number, caption, and file name types as owned rather than as references, since that is what `html_parser` supplies. Additionally, refactor the guts a bit so it is easy to see the overall logic of `rewrite_listing`, with the gnarly bits around opening and closing the rewritten listings pushed into a method on the `State` struct, itself renamed to `ListingState` and its `current_listing` field renamed to `current`. This also clarifies the semantics of each part of the rewrite operation, e.g. `ListingState::open_listing` is fallible; `ListingState::close_listing` is not.
…-support Improve handling of `<Listing>`s
mdBook does not currently have particularly good support for “external” crates. To make the test suite work correctly with `trpl`, we must first build `trpl` itself (`mdbook` will not do it), and then explicitly pass its `deps` path as a library search path for `mdbook test`. That will make sure all the crates can be resolved when running the tests. .github/workflows/main.yml
- Update the contents of the code in the chapter so it is correct, and update the text to match. Given this is about `Future`, this may also warrant moving/simplifying that whole chunk of code, too. - Update the listing to use `extern crate` since it does not otherwise work correctly with `mdbook test`. Alas.
- Update all the listings in the chapter to use `extern crate` since `mdbook test` does not understand Rust 2018. Alas. - Ignore two of the listings because they never stop.
- Update all the listings in the chapter to use `extern crate` since `mdbook test` does not understand Rust 2018. Alas. - Fix one listing which had gotten out of sync somewhere along the way. (This also fixes a comment flagged up by a reviewer!)
- Update all the listings in the chapter to use `extern crate` since `mdbook test` does not understand Rust 2018. Alas. - Ignore a listing which has a missing body apurpose.
- Rewrite the `StreamExt` definition to be more correct, and extract it to a standalone “no-listing listing” so we can make sure its definition at least type checks. - Update all the listings in the chapter to use `extern crate` since `mdbook test` does not understand Rust 2018. Alas. - Ignore the listings (inline or otherwise!) which are *intended* not to compile, so mdbook does not try to test them. - Clarify some of the text around the *actual* Tokio definition of the `StreamExt::next` method.
This does not change the actual behavior of `mdbook test`, but it does get rid of a warning about the test renderer being unsupported!
…nderer infra: support test renderer in mdbook preprocessors
15 tasks
Note: this does *not* include all fixes for the text, only for the links themselves. For the text, we will also need to search for references to chapters 17-20. This catches a few of those along the way, but there are no doubt others.
|
Heyyyy, CI is ✅ at last! That’s a great foundation to keep building on as we do further edits. |
infra: fix some shellcheck issues in CI config
Clarify function definitions vs. expressions
Co-authored-by: Tim McNamara <[email protected]> Co-authored-by: James Munns <[email protected]>
Co-authored-by: Carol (Nichols || Goulding) <[email protected]> Co-authored-by: Will Crichton <[email protected]> Co-authored-by: Tim McNamara <[email protected]>
Use the original transitional paragraph and structure, adding to it instead of rewriting it entirely. HT @timClicks (Tim McNamara <[email protected]>) for pointing out how my rephrasing here made it worse!
- Drop the history lesson and comparisons to other approaches. Focus on what async gives us instead. - Simplify and clarify the - Talk about “the network” instead of “network sockets” and simplify the example code to match.
- Swap the ordering to match the order in the text (concurrent is first, at least for now). - Make them go left-to-right instead of top-to-bottom for compactness in the text. - Fix rendering issues resulting from the VS Code extension doing things that normal `dot` does not, for who knows what reasons.
Block *everything*. We do not want any of this to be indexed, because we *only* use it for previews, and do not want its content to be cached or (especially!) surfaced to readers, since it may have a variety of issues ranging from pedagogical missteps to outright errors!
infra: add robots.txt for GH Pages previews
infra: include ghp-import and git push in generate-preview script
mdbook-trpl-listing: Add missing elided lifetimes
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Important
This is the home of our editing process. If you’re someone we asked to review the new async chapter, please see #3909 instead!
trplcrate and its dependencies when runningmdbook testso it can actually resolve them.trplcrate to pass CI, primarily by addingextern crate trpl;to each of them. Fix any bugs found bymdbook test.asyncand.awaitchapter #3909. → partial, ongoing!