Migrate mdbook-spec to this repo. #1542
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
traviscross
approved these changes
Jul 23, 2024
This just makes it a little easier to refer to them.
This code is getting long enough that it will help to organize it separately.
The std_links function was getting a little long, this should help organize a little.
If the author has an explicit link definition, don't allow std_links to override it.
Switching to a library to support upstream rustbook. Next commit will add the main back.
Switching most of the code to a library to support rustbook upstream.
This was not intended to be interpreted as rust code.
This makes a few changes to CI to handle mdbook-spec: - Adds a new job for mdbook-spec itself. - Removes caching, can set this up later. - Moves `mdbook test` to a separate job. It can be useful to see in the CI results to see which jobs are passing or failing. - Verifies the book builds with mdbook-spec. - Fix a small oversight that `style-checks` should use `--locked`. - Add a summary job to make it easier to work with merge queue and branch protections.
ehuss
added a commit
to JoelMarcey/rust-lang-spec
that referenced
this pull request
Jul 25, 2024
This has moved to the reference repo in rust-lang/reference#1542.
traviscross
added a commit
that referenced
this pull request
Jul 28, 2024
The go forward plan adopted by T-spec on 2024-06-13 includes, as one step, to reformat all of the chapters of the Reference to attach named identifiers to each claim, more or less. The resulting text will use the `mdbook-spec` extension for rendering (see PR #1542). Adding these named identifiers more granularly throughout the document is one step in allowing the Reference to be used as a specification for Rust in safety-critical applications. Per our plan, we want to reformat one chapter first, to ensure our happiness with that and to perfect our process, and to then reformat (and review and merge those reformattings of) all of the rest of the Reference chapters in the same way. We discussed and imagined that this reformatting would be somewhat mechanical, and that it could be done by a technical writer with limited experience with Rust. This is what gave us confidence that this work could be hired out, completed, and reviewed on the months-scale timeline that we had set out. As things turned out, we were fortunate enough to hire someone with significant experience with Rust. This resulted in a PR that amounts to a rewrite of the inline assembly chapter (see PR #1523). Whatever the virtues of that, it's not what we were expecting, and the degree of change in one PR has complicated and stalled effective review. This puts in jeopardy completion of the reformatting on the timeline we had expected. Consequently, this PR takes a different approach. Here, we perform *only* reformatting. That is, we add identifiers to each claim, more or less, *and nothing else*. We change *none* of the verbiage in this chapter. Contra to earlier claims that this is not possible to do, our finding, having done this, is that it works out fine. The original text was already organized reasonably well enough to just leave it in place and add the identifiers. Is this perfect? Almost certainly not. There's always more that could be done to improve a chapter. E.g., perhaps some claims could be broken down further still and more identifiers added, though there is a distinct readability tradeoff here. We've tried to strike a reasonable balance in this PR. The point of the exercise contained in this PR is that this diff is straightforward to review and moves us in the direction that we want to go. We can always make other changes later, and by separating them out, those changes will be easier to review also. Note that we're unhappy with the current rendering when two identifiers need to be stacked, e.g.: ``` [asm] [asm.intro] ``` We'll plan to improve this later and separately with work in `mdbook-spec` or in the style sheets.
traviscross
added a commit
that referenced
this pull request
Aug 6, 2024
The go forward plan adopted by T-spec on 2024-06-13 includes, as one step, to reformat all of the chapters of the Reference to attach named identifiers to each claim, more or less. The resulting text will use the `mdbook-spec` extension for rendering (see PR #1542). Adding these named identifiers more granularly throughout the document is one step in allowing the Reference to be used as a specification for Rust in safety-critical applications. Per our plan, we want to reformat one chapter first, to ensure our happiness with that and to perfect our process, and to then reformat (and review and merge those reformattings of) all of the rest of the Reference chapters in the same way. We discussed and imagined that this reformatting would be somewhat mechanical, and that it could be done by a technical writer with limited experience with Rust. This is what gave us confidence that this work could be hired out, completed, and reviewed on the months-scale timeline that we had set out. As a demonstration of the first step in that plan, this PR performs *only* reformatting. That is, we add identifiers to each claim, more or less, *and nothing else*. We change *none* of the verbiage in this chapter. Our finding is that doing things this way works out fine. The original text was already organized reasonably well enough to just leave it in place and add the identifiers. There's always more that could be done to improve a chapter. E.g., perhaps some claims could be broken down further still and more identifiers added, though there is a distinct readability tradeoff here. We've tried to strike a reasonable balance in this PR. The point of the exercise contained in this PR is that this diff is straightforward to review and moves us in the direction that we want to go. We can always make other changes later, and by separating them out, those changes will be easier to review also. Note that we're unhappy with the current rendering when two identifiers need to be stacked, e.g.: ``` [asm] [asm.intro] ``` We'll plan to improve this later and separately with work in `mdbook-spec` or in the style sheets.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This migrates the mdbook-spec plugin from the https://github.com/rust-lang/spec/ repository to this repository. This is done for a few reasons:
This was made possible by the recent change of rust-lang/rust#127786.
There shouldn't be any changes to the plugin compared to the spec repo.
This changes CI to split the work across multiple jobs. This can make it easier to see which parts are failing, for example if multiple things are failing, before you could only see one at a time. However, this requires a change to the team repo at rust-lang/team#1502 before it can merge.