]> git.lizzy.rs Git - rust.git/commit - src/tools/miri
Rollup merge of #101166 - GuillaumeGomez:error-index-mdbook, r=notriddle
authorGuillaume Gomez <guillaume1.gomez@gmail.com>
Fri, 2 Sep 2022 09:34:51 +0000 (11:34 +0200)
committerGitHub <noreply@github.com>
Fri, 2 Sep 2022 09:34:51 +0000 (11:34 +0200)
commit68d3cfac47c4ccd6d057045ff00d0e2e9e46e800
tree21e6f491a15cac8d88a0e07141622a4fdf091628
parent203526e576935c75b5ca23a490ea53cee361079c
parentf5857d5c5e1d2fde302f330d11c5cdea8005eb2a
Rollup merge of #101166 - GuillaumeGomez:error-index-mdbook, r=notriddle

Generate error index with mdbook instead of raw HTML pages

This is a follow-up of https://github.com/rust-lang/rust/pull/100922.

This comes from a remark from ````@estebank```` who said that the search was a nice thing on the previous version and that it wasn't possible anymore. An easy way to come around this limitation was to use `mdbook`, which is what I did here.

Now some explanations on the code. I'll explain how I developed this and why I reached this solution. First I did it very basically by simply setting the source directory and the output directory, generated a `SUMMARY.md` manually which listed all error codes and that was it. Two problems arose from this:
 1. A lot of new HTML files were generated at the top level
 2. An `index.html` file was generated at the top-level (the summary in short).

So for `1.`, it's not great to have too many files at the top-level as it could create file conflicts more easily. And for `2.`, this is actually a huge issue because <doc.rust-lang.org> generates an `index.html` file with a links to a few different resources, so it should never be overwritten. <s>Unfortunately, `mdbook` **always** generates an `index.html` file so the only solution I could see (except for sending them a contribution, I'll maybe do that later) was to temporaly move a potentially existing `index.html` file and then puts it back once done. For this last part, to ensure that we don't return *before* it has been put back, I wrapped the `mdbook` generation code inside `render_html_inner` which is called from `render_html` which in turn handle the "save" of `index.html`.</s>

EDIT: `mdbook` completely deletes ALL the content in the target directory so I instead generate into a sub directory and then I move the files to the real target directory.

To keep compatibility with the old version, I also put the `<script>` ````@notriddle```` nicely provided in the previous PR only into the `error-index.html` file to prevent unneeded repetition. I didn't use `mdbook` `additional-js` option because the JS is included at the end of all HTML files, which we don't want for two reasons:
 1. It's slow.
 2. We only want it to be run in `error-index.html` (even if we also ensure in the JS itself too!).

<s>Now the last part: why we generate the summary twice. We actually generate it once to tell `mdbook` what the book will look like and a second time because a create a new chapter content which will actually list all the error codes (with the updated paths).</s>

EDIT: I removed the need for two summaries.

You can test it [here](https://rustdoc.crud.net/imperio/error-index-mdbook/error-index.html).

r? ````@notriddle````
Cargo.lock