These docs were slightly drifting from the user guide docs. Instead of
trying to maintain multiple copies of this, I have changed it so that
it just links out to the guide.
(The guide docs could be cleaned up a little, but that's a separate
issue.)
This does a little cleanup around the usage of filesystem functions:
- Add `mdbook_core::utils::fs::read_to_string` as a wrapper around
`std::fs::read_to_string` to provide better error messages. Use
this wherever a file is read.
- Add `mdbook_core::utils::fs::create_dir_all` as a wrapper around
`std::fs::create_dir_all` to provide better error messages. Use
this wherever a file is read.
- Replace `mdbook_core::utils::fs::write_file` with `write` to mirror
the `std::fs::write` API.
- Remove `mdbook_core::utils::fs::create_file`. It was generally not
used anymore.
- Scrub the usage of `std::fs` to use the new wrappers. This doesn't
remove it 100%, but it is now significantly reduced.
These functions are only used by the links preprocessor. I'm moving
these functions to put them closer to the code that they are associated
with, and to reduce the public API surface.
This switches to using the tracing crate instead of log. Tracing
provides a lot of nice features which we can take advantage of moving
forward.
This also adjusts the output fairly significantly. This includes:
- Switched the environment variable from RUST_LOG to MDBOOK_LOG.
- Dropped the timestamp. I experimented with various different time
displays, but ultimately decided to omit it for now. I don't think
I've ever found it to be useful, and it takes up a very significant
amount of space. It could potentially be useful for basic profiling,
but I think there are other, better mechanisms for that. We could
consider leveraging tracing itself for doing some basic profiling
(like using something like tracing-chrome).
- Dropped the target unless MDBOOK_LOG is set. The target tends to be
pretty noisy, and doesn't really convey much information unless you
are debugging or otherwise trying to adjust the log output.
- Added color.
- Slightly reworked the way the error cause trace is displayed.
- Slightly changed the way html5ever filtering is done, as well as add
handlebars to the list since they both are very noisy. You can
override this now by explicitly listing them as targets.
I still expect that mdbook will eventually change how it displays things
to the console, possibly switching away from tracing and printing things
itself. However, that is a larger project for the future.
This adds the `optional` field to the preprocessor configuration to
mirror the same option for the `output` table. Missing preprocessors are
now an error unless the `optional` field is set. This should help with
inadvertently building a book when a missing preprocessor that you
expect to be installed.
This changes preprocessors so that:
- Relative paths in the `command` value are relative to the book root.
- The process current directory is the book root.
This makes it so that it isn't dependent on the directory where `mdbook`
is executed.
Fixes https://github.com/rust-lang/mdBook/issues/1424
This switches all public types to use non_exhaustive to make it easier
to make additions without a semver-breaking change.
Some of the ergonomics are hampered due to the lack of exhaustiveness
checking. Hopefully some day in the future,
non_exhaustive_omitted_patterns_lint or something like it will get
stabilized.
Closes https://github.com/rust-lang/mdBook/issues/1835
