From aaca44f62b8e562cef5044c4f61ff20e45b97c73 Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Tue, 30 May 2023 17:04:19 +0200 Subject: [PATCH] Format files with `dprint` (#711) The dprint formatter is a flexible system which will use sandboxed WebAssembly formatters to format our code (mostly: it calls out to `rustfmt` for Rust code). A particularly interesting feature is that dprint can format Rust code blocks in the Markdown files. However, before we turn that on, we need to have a way to normalize the Markdown text as it is extracted[1]. That is so that the word put into the translations is kept after the reformatting. [1]: https://github.com/google/mdbook-i18n-helpers/issues/19 --- .github/workflows/build.yml | 4 ++-- CONTRIBUTING.md | 4 ++-- README.md | 10 ++++++---- STYLE.md | 24 +++++++++++++++--------- TRANSLATIONS.md | 10 +++++----- dprint.json | 30 ++++++++++++++++++++++++++++++ mdbook-exerciser/Cargo.toml | 4 ++-- mdbook-exerciser/README.md | 7 ++++--- rustfmt.toml | 2 +- 9 files changed, 67 insertions(+), 28 deletions(-) create mode 100644 dprint.json diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 89e5e569..62617b76 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -21,8 +21,8 @@ jobs: rustup default nightly rustup component add rustfmt - - name: Check Rust formatting - run: cargo fmt --all -- --check + - name: Check formatting + uses: dprint/check@v2.2 cargo: runs-on: ubuntu-latest diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6272489d..b05194d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,5 +24,5 @@ information on using pull requests. ## Community Guidelines -This project follows [Google's Open Source Community -Guidelines](https://opensource.google/conduct/). +This project follows +[Google's Open Source Community Guidelines](https://opensource.google/conduct/). diff --git a/README.md b/README.md index e43d25cb..d030bbfc 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ trigger when going through the code samples. We hope to improve on this via ## Building The course is built using a few tools: + - [mdbook](https://github.com/rust-lang/mdBook) - [mdbook-svgbob](https://github.com/boozook/mdbook-svgbob) - [mdbook-i18n-helpers](https://github.com/google/mdbook-i18n-helpers) @@ -64,9 +65,10 @@ and zip exercises and add them to `book/html`. To build any of the translated versions of the course, run `MDBOOK_BOOK__LANGUAGE=xx mdbook build -d book/xx` where `xx` is the ISO 639 language code (e.g. `da` for the Danish translation). [TRANSLATIONS.md](TRANSLATIONS.md) contains further instructions. + ## Contact -For questions or comments, please contact [Martin -Geisler](mailto:mgeisler@google.com) or start a [discussion on -GitHub](https://github.com/google/comprehensive-rust/discussions). We would love -to hear from you. +For questions or comments, please contact +[Martin Geisler](mailto:mgeisler@google.com) or start a +[discussion on GitHub](https://github.com/google/comprehensive-rust/discussions). +We would love to hear from you. diff --git a/STYLE.md b/STYLE.md index c1f9eb5a..565507d4 100644 --- a/STYLE.md +++ b/STYLE.md @@ -37,11 +37,17 @@ When showing Rust code, please use the same spacing as `rustfmt`: `3 * x` instead of `3*x`. However, feel free to remove newlines when it can make the code more compact and easier to understand, e.g., you can use + + ```rust struct Person { name: String } ``` -if you like. + + +if the `Person` struct is not important for your example. Please use this +sparingly: enclose the code block in `` and +`` to suppress warnings about the formatting. ## Speaker Notes @@ -61,8 +67,8 @@ collapsed or removed entirely from the slide. ## Translations -This section is about what you write in the translation. We describe [how to -create or update translations elsewhere](TRANSLATIONS.md). +This section is about what you write in the translation. We describe +[how to create or update translations elsewhere](TRANSLATIONS.md). When translating the course, please take the following into account: @@ -70,18 +76,18 @@ When translating the course, please take the following into account: easily understood in your language, please add the translated version after the original name. -- If the Rust Book has been [translated into your - language](https://doc.rust-lang.org/book/appendix-06-translation.html), please - use the same vocabulary. +- If the Rust Book has been + [translated into your language](https://doc.rust-lang.org/book/appendix-06-translation.html), + please use the same vocabulary. - Be careful to preserve the Markdown syntax of the original text. Pay special attention to reference links in all their variations: `[foo][bar]`, `[foo][]` (which means `[foo][foo]`), and `[foo]` (which also means `[foo][foo]`). As an example, if you translate `[foo]`, to `[FOO]`, you must also update the - corresponding link definition from `[foo]: https://example.net` to `[FOO]: - https://example.net`. If you forget to do this, you end up with a broken link - in the translation. + corresponding link definition from `[foo]: https://example.net` to + `[FOO]: https://example.net`. If you forget to do this, you end up with a + broken link in the translation. - If you find mistakes or things that sound awkward in the original English text, please submit PRs to fix them! Fixing typos in the translation is great, diff --git a/TRANSLATIONS.md b/TRANSLATIONS.md index c192f29e..ddaa8ed1 100644 --- a/TRANSLATIONS.md +++ b/TRANSLATIONS.md @@ -5,9 +5,9 @@ languages! We use the [Gettext] system for translations. This means that you don't modify the Markdown files directly: instead you modify `.po` files in a `po/` directory. The `.po` files are small text-based translation databases. -> **Tip:** You should not edit the `.po` files by hand. Instead use a PO -> editor, such as [Poedit](https://poedit.net/). There are also several online -> editors available. This will ensure that the file is encoded correctly. +> **Tip:** You should not edit the `.po` files by hand. Instead use a PO editor, +> such as [Poedit](https://poedit.net/). There are also several online editors +> available. This will ensure that the file is encoded correctly. There is a `.po` file for each language. They are named after the [ISO 639] language codes: Danish would go into `po/da.po`, Korean would go into @@ -25,9 +25,9 @@ GNU Gettext utilities below. We use two helpers for the translations: -* `mdbook-xgettext`: This program extracts the English text. It is an mdbook +- `mdbook-xgettext`: This program extracts the English text. It is an mdbook renderer. -* `mdbook-gettext`: This program translates the book into a target language. It +- `mdbook-gettext`: This program translates the book into a target language. It is an mdbook preprocessor. Install both helpers with: diff --git a/dprint.json b/dprint.json new file mode 100644 index 00000000..7c6da785 --- /dev/null +++ b/dprint.json @@ -0,0 +1,30 @@ +{ + "lineWidth": 80, + "json": {}, + "markdown": { + "textWrap": "always" + }, + "toml": {}, + "exec": { + "associations": "**/*.rs", + "rustfmt": "rustfmt --edition 2021", + "rustfmt.associations": "**/*.rs" + }, + "includes": [ + "**/*.json", + "**/*.md", + "**/*.rs", + "**/*.toml" + ], + "excludes": [ + "/src/", + "/third_party/", + "target/" + ], + "plugins": [ + "https://plugins.dprint.dev/exec-0.3.5.json@d687dda57be0fe9a0088ccdaefa5147649ff24127d8b3ea227536c68ee7abeab", + "https://plugins.dprint.dev/json-0.17.2.wasm", + "https://plugins.dprint.dev/markdown-0.15.2.wasm", + "https://plugins.dprint.dev/toml-0.5.4.wasm" + ] +} diff --git a/mdbook-exerciser/Cargo.toml b/mdbook-exerciser/Cargo.toml index 31195e97..56f7a25f 100644 --- a/mdbook-exerciser/Cargo.toml +++ b/mdbook-exerciser/Cargo.toml @@ -1,11 +1,11 @@ [package] name = "mdbook-exerciser" version = "0.1.0" +authors = ["Andrew Walbran "] edition = "2021" license = "Apache-2.0" -authors = ["Andrew Walbran "] -description = "A tool for extracting starter code for exercises from Markdown files." repository = "https://github.com/google/comprehensive-rust" +description = "A tool for extracting starter code for exercises from Markdown files." [dependencies] anyhow = "1.0.68" diff --git a/mdbook-exerciser/README.md b/mdbook-exerciser/README.md index 03db92b1..3438ccf7 100644 --- a/mdbook-exerciser/README.md +++ b/mdbook-exerciser/README.md @@ -1,7 +1,7 @@ # exerciser -This is an mdBook renderer to generate templates for exercises from the Markdown source. Given a -Markdown file `example.md` with one or more sections like: +This is an mdBook renderer to generate templates for exercises from the Markdown +source. Given a Markdown file `example.md` with one or more sections like: ````markdown @@ -22,5 +22,6 @@ and mdbook configuration in `book.toml` like: output-directory = "comprehensive-rust-exercises" ``` -It will create a file `book/exerciser/comprehensive-rust-exercises/example/src/main.rs` with the +It will create a file +`book/exerciser/comprehensive-rust-exercises/example/src/main.rs` with the appropriate contents. diff --git a/rustfmt.toml b/rustfmt.toml index 40b837b3..f3c72b99 100644 --- a/rustfmt.toml +++ b/rustfmt.toml @@ -1,2 +1,2 @@ -imports_granularity = "module" # Please use nightly for this setting. +imports_granularity = "module" # Please use nightly for this setting. max_width = 90