This uses the `rustfmt` from the stable toolchain, instead of nightly.
At the moment, nightly's `rustfmt` is nonfunctional, but in general we
don't need bleeding-edge formatting (and in fact, the more often
formatting changes, the more often we'll get spurious failures on PRs,
as we are today).
Fixes#2165.
Without this, several of the formatting directives in our `rustfmt.toml`
file won’t have any effect. This will in turn lead to mismatches between
the formatting done locally and in CI.
This creates a dependency on `rustup`, but I think this is overall
better than silently ignoring the formatting directives.
From the discussion in #1682.
Before we would run `mdbook test` using the current Markdown sources.
This is subtly wrong: we publish the course using back-dated sources,
so we should therefore also run the tests using the same sources (this
ensures that the code snippets actually work).
After this commit, all translatable content lives in exactly two
directories:
- `src/`
- `third_party/`
We need to restore both directories when testing and when publishing.
This ensures consistency in the Markdown text and in the included
source code.
A new `.github/workflows/build.sh` script takes care of preparing the
two directories according to the date in the PO file (if any).
To ensure we can restore all of `third_party/` to an old commit, the
non-changing `third_party/mdbook/book.js` file has been moved to
`theme/book.js`. The file is generated by `mdbook init --theme`,
making it suitable for modification by the user (us). Symlinks have
been added to `third_party/mdbook/` to indicate that the files
ultimately came from upstream.
This is the result of running `dprint fmt` after removing `src/` from
the list of excluded directories.
This also reformats the Rust code: we might want to tweak this a bit in
the future since some of the changes removes the hand-formatting. Of
course, this formatting can be seen as a mis-feature, so maybe this is
good overall.
Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged
after this, meaning that all existing translations remain valid! A few
messages were changed because of stray whitespace characters:
msgid ""
"Slices always borrow from another object. In this example, `a` has to remain "
-"'alive' (in scope) for at least as long as our slice. "
+"'alive' (in scope) for at least as long as our slice."
msgstr ""
The formatting is enforced in CI and we will have to see how annoying
this is in practice for the many contributors. If it becomes annoying,
we should look into fixing dprint/check#11 so that `dprint` can annotate
the lines that need fixing directly, then I think we can consider more
strict formatting checks.
I added more customization to `rustfmt.toml`. This is to better emulate
the dense style used in the course:
- `max_width = 85` allows lines to take up the full width available in
our code blocks (when taking margins and the line numbers into account).
- `wrap_comments = true` ensures that we don't show very long comments
in the code examples. I edited some comments to shorten them and avoid
unnecessary line breaks — please trim other unnecessarily long comments
when you see them! Remember we're writing code for slides 😄
- `use_small_heuristics = "Max"` allows for things like struct literals
and if-statements to take up the full line width configured above.
The formatting settings apply to all our Rust code right now — I think
we could improve this with https://github.com/dprint/dprint/issues/711
which lets us add per-directory `dprint` configuration files. However,
the `inherit: true` setting is not yet implemented (as far as I can
tell), so a nested configuration file will have to copy most or all of
the top-level file.
This enforces a consistent formatting for the PO files. The goal of this
is to avoid large diffs due to random and unnecessary reformatting.
We use the format of `msgcat`: this is also waht `msgmerge` produces and
it’s easy to replicate for people by installing Gettext and running
`dprint fmt`.
This is a follow-up to #1351 which started enforcing that the `msgid`
fields don’t change due to reformatting in a PR.
If this turns out to be cumbersome, then we can disable it again.
Initially, I also formatted the templates in `theme/`, but this triggers
https://github.com/prettier/prettier/issues/11834. So I exclude them for
now.
---------
Co-authored-by: Ming-Ying Chung <mych@chromium.org>
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
