We are already using `cargo xtask install-tools` to install the
project's tools, and `cargo xtask web-tests` to run the js tests. In
this PR we provide support for the various `mdbook` commands
(`test`,`serve`, and `build`) with `cargo xtask` commands. This provides
a uniform interface for running tasks in the project. Additionally it
allows these commands to work from within any dirrectory (previously
you'd need to navigate to the workspace root in order to run say `mdbook
build`).
Additionally we're improving the xtask code by making use of `Clap`
enums to handle validation of the possible tasks to run via xtask (this
closes#2741 ).
---------
Co-authored-by: Eric Githinji <egithinji@google.com>
### Background
Comprehensive Rust requires a number of tools to be installed (e.g.
mdbook and mdbook-course). As mentioned in #2509 (and discussed in
#2469) it would be nice to have a cross platform command for installing
these dependencies. Currently these are installed using a shell script
(`install-mdbook.sh`) but this isn't truly cross platform e.g. for
Windows users.
### Xtask
[xtask](https://github.com/matklad/cargo-xtask) outlines an approach for
automating tasks in a Rust project. It involves using cargo's aliasing
feature to allow us to run commands like `cargo xtask <some task>` to
perform adhoc tasks via a Rust binary that we might otherwise need a
shell script for.
In this PR we add support for a `cargo xtask install-tools` command that
will replace the `install-mdbook.sh` script and install the dependent
tools. We can potentially extend it to support for other tasks e.g.
`cargo xtask fmt`.
---------
Co-authored-by: Eric Githinji <egithinji@google.com>
Move mdbook installation into a script and use exact versions from the
CI.
Update README.md to instruct developers to use the same versions as the
CI to sync both environments.
This is related to #2620 and it fixes#2588
In #2153 I aimed to fix a link but broke it.
In this PR, I fix it and add
[`mdbook-linkcheck`](https://github.com/Michael-F-Bryan/mdbook-linkcheck)
to avoid future cases.
Some past fixes that could have been prevented, in addition to mine in
this PR:
* #811
* #2064
* #2146
Note:
`mdbook-linkcheck` may also check external links with a configuration
change.
It can be beneficial to check also external links from time to time. I
ran it here and found 3 broken links.
Maintainers - sorry for the lack of a preceding issue. We can discuss it
here.
Some remaining work is to fix the outdated internal links in the
translations, not done here.
Let me know what you think about the proposed contribution.
This PR completes #1502.
Reverts google/comprehensive-rust#1975
Using `mdbook-pandoc` requires more than just installing the `mdbook`
plugin: it requires
- A whole LaTeX installation
- A Pandoc installation
- Some fonts
This is essentially why the output is configured as optional in
`book.toml`: the assumption is that people won't have `mdbook-pandoc`
installed without the necessary supporting tools.
@henrif75, I assume you added this because you didn't like the warning
`mdbook build` prints:
```
% mdbook build
2024-04-16 10:45:56 [WARN] (mdbook::book): The output.html.curly-quotes field has been renamed to output.html.smart-punctuation.
Use the new name in book.toml to remove this warning.
2024-04-16 10:45:56 [INFO] (mdbook::book): Book building has started
2024-04-16 10:45:57 [INFO] (mdbook::book): Running the exerciser backend
2024-04-16 10:45:57 [INFO] (mdbook::renderer): Invoking the "exerciser" renderer
2024-04-16 10:45:57 [INFO] (mdbook::book): Running the html backend
2024-04-16 10:45:58 [INFO] (mdbook::book): Running the pandoc backend
2024-04-16 10:45:58 [INFO] (mdbook::renderer): Invoking the "pandoc" renderer
2024-04-16 10:45:58 [WARN] (mdbook::renderer): The command `mdbook-pandoc` for backend `pandoc` was not found, but was marked as optional.
```
I don't have the necessary dependencies on my local system and this is
what I get after installing `mdbook-pandoc`:
```
2024-04-16 10:47:30 [INFO] (mdbook::renderer): Invoking the "pandoc" renderer
Unable to run `pandoc -v`: No such file or directory (os error 2)
2024-04-16 10:47:30 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code.
2024-04-16 10:47:30 [ERROR] (mdbook::utils): Error: Rendering failed
2024-04-16 10:47:30 [ERROR] (mdbook::utils): Caused By: The "pandoc" renderer failed
```
This also means that `mdbook serve` doesn't work unless all dependencies
are installed.
As an alternative, we could remove the `output.pandoc` settings from the
`book.toml` file and use a small shell script to add them when needed.
We actually have the same problem for the `mdbook-xgettext` output
format which generates the POT files: we only want to run this
occasionally. This is currently done by overriding `output` from the
command line using the `MDBOOK_OUTPUT` environment variable:
```shell
MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot", "granularity": 0}}' \
mdbook build -d po
```
It's a bit ugly and it results in people missing/forgetting some of the
configuration options we want them to use (the `granularity` setting).
So I would like to move this configuration to the `book.toml` file — but
I'm reluctant since I don't think we need to generate POT files on every
build (it takes ~1 second and would slow down `mdbook serve`).
Cc @max-heller in case you have ideas here.
This is a contribution of a Chromium section for Comprehensive Rust.
---------
Co-authored-by: Nicole L <dlegare.1001@gmail.com>
Co-authored-by: Martin Geisler <martin@geisler.net>
I hope the blog post can help shed more light on why we wrote the course
and how it has been used at Google.
I'm not sure if "Press" is the best title, but I hope to link other
articles later from this section at a later point.
In v2 of the course, I'd like to include an estimate of the time to be
spent on each segment in the Markdown file. I think a good place for
such metadata is in the frontmatter.
For review purposes, though, I just want to display that information.
So, this is a start at a new mdbook preprocessor that just separates out
the frontmatter and includes it in a `<pre>` block. Eventually, I'd like
to parse it and put the time in the speaker notes.
---------
Co-authored-by: Martin Geisler <martin@geisler.net>
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
* Align outline with new spin-off course structure
With the new structure, the section on Android is a spin-off course
from the main 3-day course on Rust Fundamentals. The Bare-metal and
Concurrency days are spin-off courses in the same way.
* Explain new course structure
* Align Bare-Metal welcome page with other deep dives
* Merge Day 4 page into Course Structure page
* Remove Day 4 Welcome page
This aligns the Concurrency in Rust section with the Bare-Metal Rust
deep dive.
* Show subsections for Android deep dive
This aligns the Rust in Android section with the other deep dives.
* Clean up welcome page and README
We now cover async Rust and the course is no longer a four day course.
* Remove reference to the old Day 4
* Remove Day 4 references from exercises
The i18n-helpers are now available as a stand-alone crate:
https://crates.io/crates/mdbook-i18n-helpers.
Because we cache the Rust binaries in our GitHub workflows, I bumped
the cache prefix to ensure we use a clean cache. Otherwise, Cargo
won’t install the new binaries in mdbook-i18n-helpers because it sees
the old ones from this repository.
* Make i18n-helpers a requirement
* Skip mdbook-gettext for mdbook-xgettext
* Gettext finds PO file based on `book.language`
* Update workflow
No need to set `preprocessor.gettext.po-file`.
---------
Co-authored-by: Jooyung Han <jooyung@google.com>
