diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2f2b9b29a5..82746b223f 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -107,6 +107,23 @@ jobs: working-directory: ./xtask run: cargo fmt --check + reference-dev-guide: + name: reference-dev-guide build check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@master + - name: Install mdbook + env: + MDBOOK_VERSION: 0.5.1 + run: | + mkdir bin + curl -sSL https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin + echo "$(pwd)/bin" >> $GITHUB_PATH + - name: Check reference-dev-guide build + run: | + cd reference-dev-guide + mdbook build + preview: if: github.event_name == 'pull_request' runs-on: ubuntu-latest @@ -153,6 +170,7 @@ jobs: - code-tests - style-tests - mdbook-spec + - reference-dev-guide # preview is explicitly excluded here since it doesn't run on merge runs-on: ubuntu-latest steps: diff --git a/.github/workflows/reference-dev-guide.yml b/.github/workflows/reference-dev-guide.yml new file mode 100644 index 0000000000..6007693f11 --- /dev/null +++ b/.github/workflows/reference-dev-guide.yml @@ -0,0 +1,49 @@ +name: Deploy reference-dev-guide +on: + push: + branches: + - master + +env: + MDBOOK_VERSION: 0.5.1 + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + + - name: Install mdbook + run: | + mkdir mdbook + curl -Lf https://github.com/rust-lang/mdBook/releases/download/v${{ env.MDBOOK_VERSION }}/mdbook-v${{ env.MDBOOK_VERSION }}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook + echo `pwd`/mdbook >> $GITHUB_PATH + + - name: Build the book + run: | + cd reference-dev-guide + mdbook build + mkdir out + touch out/.nojekyll + mv book out/reference-dev-guide + + - name: Upload Artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./reference-dev-guide/out + + deploy: + needs: build + + permissions: + pages: write + id-token: write + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cc2acb9767..6edf2913c5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,76 +1,3 @@ -Thank you for your interest in contributing to the Rust Reference! +# Contributing to The Rust Reference -There are a few ways of helping with the reference: critiquing the reference, -editing the reference, fixing incorrect information, adding examples and -glossary entries, and documenting new or otherwise undocumented features in -Rust. - -For a while, the Reference was basically ignored, and Rust continued gaining new -features or changing old ones. It was also basically the introduction document -before the first edition of the Rust book, and constantly in flux from the huge -churn of the language design before v1.0.0. So there's a lot that's wrong, too -teachy for people who should have basic understanding of Rust, or is too shallow -for the Reference. As such, we have the warning saying there's work that needs -to be done. Eventually, we plan to make sure everything is well documented -enough that we can remove the warning. - -It is encouraged for you to read the [introduction] to familiarize yourself with -the kind of content the reference is expected to contain and the conventions it -uses. Also, the [Authoring Guide] provides more detailed guidelines for -formatting and content. - -## Critiquing the Reference - -This is the easiest way to contribute. Basically, as you read the reference, if -you find something confusing, incorrect, or missing, then you can file an issue -against the reference explaining your concerns. - -## Editing the Reference - -Typos and incorrect links get through from time to time. Should you find them, -we welcome PRs to fix them. Additionally, larger editing jobs that help remove -the number of parentheticals, remove comma splices, italicize term definitions -and other similar tasks are helpful. - -## Adding examples and glossary entries - -Examples are great. Many people will only read examples and ignore the prose. -Ideally, every facet of every feature will have an example. - -Likewise, the reference has a glossary. It doesn't need to explain every facet -of every feature nor contain every definition, but it does need to be expanded -upon. Ideally entries in the glossary link to the associated documentation. - -## Adding documentation - -There are a lot of features that are not documented at all or are documented -poorly. This is the hardest, but definitely most valuable. Pick an unassigned -issue from the [issue tracker], and write about it. - -While writing, you may find it handy to have a [playpen] open to test out what -you are documenting. - -Feel free to take information from the standard library and Rustonomicon as -appropriate. - -Note that we don't write documentation for purely library features such as -threads and IO and we don't write about Rust in the future. Documentation is -written as if the current stable release of Rust is the last release. The -`master` branch of the reference corresponds to what is **stable** on the -`master` branch ("nightly") of [rust-lang/rust]. If you want to write about -Rust in the future, you want [the Unstable book][unstable]. - -## Stabilization - -When something that alters the language is stabilized, an issue should be -opened on the reference [issue tracker] to track the documentation process. -This should include links to any relevant information, such as the -stabilization PR, the RFC, the tracking issue, and anything else that would be -helpful for writing the documentation. - -[Authoring Guide]: docs/authoring.md -[introduction]: src/introduction.md -[issue tracker]: https://github.com/rust-lang/reference/issues -[playpen]: https://play.rust-lang.org/ -[rust-lang/rust]: https://github.com/rust-lang/rust/ -[unstable]: https://doc.rust-lang.org/nightly/unstable-book/ +See the [Reference Developer Guide](https://rust-lang.github.io/reference/reference-dev-guide/) for information on contributing to the Reference. diff --git a/README.md b/README.md index 1db891c78f..a06d5c10da 100644 --- a/README.md +++ b/README.md @@ -4,91 +4,4 @@ This document is the primary reference for the Rust programming language. ## Contributor docs -There are several pages for those working on the reference: - -* [Authoring guide](https://github.com/rust-lang/reference/blob/master/docs/authoring.md): Guidelines for writing content. -* [Review policy](https://github.com/rust-lang/reference/blob/master/docs/review-policy.md): Guidelines for reviewers. -* [Grammar](https://github.com/rust-lang/reference/blob/master/docs/grammar.md): How the grammar syntax works. -* [Attribute template](https://github.com/rust-lang/reference/blob/master/docs/attribute-template.md): The standard template for documenting an attribute. - -## Building - -To build the Reference, first clone the project: - -```sh -git clone https://github.com/rust-lang/reference.git -cd reference -``` - -(Alternatively, if you don't want to use `git`, [download][] a ZIP file -of the project, extract it using your preferred tool, and rename the -top-level directory to `reference`.) - -[download]: https://github.com/rust-lang/reference/archive/refs/heads/master.zip - -### Installing mdbook - -The Reference is built using [mdbook]. - -First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed in order to run the tests: - -```sh -rustup toolchain install nightly -rustup override set nightly -``` - -Now, ensure you have `mdbook` installed, as this is needed in order to build the Reference: - -```sh -cargo install --locked mdbook -``` - -[mdbook]: https://rust-lang.github.io/mdBook/ - -### Running mdbook - -`mdbook` provides a variety of different commands and options to help you work on the book: - -* `mdbook build --open`: Build the book and open it in a web browser. -* `mdbook serve --open`: Launches a web server on localhost. It also automatically rebuilds the book whenever any file changes and automatically reloads your web browser. - -The book contents are driven by a `SUMMARY.md` file, and every file must be linked there. See for its usage. - -### `SPEC_RELATIVE` - -The `SPEC_RELATIVE=0` environment variable makes links to the standard library go to instead of being relative, which is useful when viewing locally since you normally don't have a copy of the standard library. - -```sh -SPEC_RELATIVE=0 mdbook serve --open -``` - -The published site at (or local docs using `rustup doc`) does not set this, which means it will use relative links which supports offline viewing and links to the correct version (for example, links in will stay within the 1.81.0 directory). - -### `SPEC_DENY_WARNINGS` - -The `SPEC_DENY_WARNINGS=1` environment variable will turn all warnings generated by `mdbook-spec` to errors. This is used in CI to ensure that there aren't any problems with the book content. - -### `SPEC_RUST_ROOT` - -The `SPEC_RUST_ROOT` can be used to point to the directory of a checkout of . This is used by the test-linking feature so that it can find tests linked to reference rules. If this is not set, then the tests won't be linked. - -## Running tests - -There are several different kinds of tests you can run (these are enforced on CI): - -* `mdbook test`: This will run the inline Rust codeblocks (internally it uses `rustdoc` to do this). -* `cargo xtask style-check`: This will validate some style checks (see [authoring guide](docs/authoring.md)). -* `cargo xtask linkcheck`: This will validate that markdown links aren't broken. -* `cargo xtask test-all`: Runs all tests. - -## How is this published? - -The process for getting the reference content into a [Rust release](https://doc.rust-lang.org/reference/#rust-releases) and on the website is: - -1. Changes are merged to this repository. -2. [Triagebot](https://forge.rust-lang.org/triagebot/doc-updates.html) will automatically synchronize this repository to [rust-lang/rust]. This happens every other week. The reference is tracked in [rust-lang/rust] as a [submodule](https://github.com/rust-lang/rust/tree/master/src/doc). - - This will open a PR on [rust-lang/rust] which needs to be merged, and that can take up to several days. -3. At midnight UTC, whatever is on the default branch of [rust-lang/rust] will be a part of that nightly release, and will be published after a few hours to . -4. Following Rust's [release process](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html), every 6 weeks, nightly will be promoted to beta (), and then 6 weeks after that it will be promoted to stable (). - -[rust-lang/rust]: https://github.com/rust-lang/rust/ +See the [Reference Developer Guide](https://rust-lang.github.io/reference/reference-dev-guide/) for information on contributing to the Reference. diff --git a/STYLE.md b/STYLE.md deleted file mode 100644 index 5a64884615..0000000000 --- a/STYLE.md +++ /dev/null @@ -1,5 +0,0 @@ -# Rust reference style guide - -See the [Authoring Guide] for details on the style used in the reference. - -[Authoring Guide]: docs/authoring.md diff --git a/docs/authoring.md b/docs/authoring.md index 1d09bb2fe2..f23b8b79b2 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -4,203 +4,6 @@ This document serves as a guide for editors and reviewers. Some conventions and [introduction]: ../src/introduction.md -## Markdown formatting - -* Use [ATX-style headings][atx] (not Setext) with [sentence case]. -* Do not use tabs, only spaces. -* Files must end with a newline. -* Lines must not end with spaces. Double spaces have semantic meaning, but can be invisible. Use a trailing backslash if you need a hard line break. -* If possible, avoid double blank lines. -* Do not use indented code blocks; use 3+ backticks code blocks instead. -* Code blocks should have an explicit language tag. -* Do not wrap long lines. This helps with reviewing diffs of the source. -* Use [smart punctuation] instead of Unicode characters. For example, use `---` for em-dash instead of the Unicode character. Characters like em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters. -* Links should be relative with the `.md` extension. Links to other rust-lang books that are published with the reference should also be relative so that the linkchecker can validate them. -* Links to the standard library should use rustdoc-style links described in [Standard library links](#standard-library-links). -* The use of reference links is preferred, with shortcuts if appropriate. Place the sorted link reference definitions at the bottom of the file, or at the bottom of a section if there are an unusually large number of links that are specific to the section. - - ```markdown - Example of shortcut link: [enumerations] - Example of reference link with label: [block expression][block] - - [block]: expressions/block-expr.md - [enumerations]: types/enum.md - ``` -* See the [Conventions] section for formatting callouts such as notes, edition differences, and warnings. - -There are automated checks for some of these rules. Run `cargo xtask style-check` to run them locally. - -[atx]: https://spec.commonmark.org/0.31.2/#atx-headings -[conventions]: ../src/introduction.md#conventions -[sentence case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case -[smart punctuation]: https://rust-lang.github.io/mdBook/format/markdown.html#smart-punctuation - -### Code examples - -Code examples should use code blocks with triple backticks. The language should always be specified (such as `rust`). - -```rust -println!("Hello!"); -``` - -See for a list of supported languages. - -Rust examples are tested via rustdoc, and should include the appropriate annotations: - -* `edition2015`, `edition2018`, etc. --- If it is edition-specific (see `book.toml` for the default). -* `no_run` --- The example should compile successfully, but should not be executed. -* `should_panic` --- The example should compile and run, but produce a panic. -* `compile_fail` --- The example is expected to fail to compile. -* `ignore` --- The example shouldn't be built or tested. This should be avoided if possible. Usually this is only necessary when the testing framework does not support it (such as external crates or modules, or a proc-macro), or it contains pseudo-code which is not valid Rust. An HTML comment such as `` should be placed before the example to explain why it is ignored. -* `Exxxx` --- If the example is expected to fail to compile with a specific error code, include that code so that rustdoc will check that the expected code is used. - -When demonstrating success cases, many such cases may be included in a single code block. For failure cases, however, each example must appear in a separate code block so that the tests can ensure that each case indeed fails and fails with the appropriate error code or codes. - -See the [rustdoc documentation] for more detail. - -[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html - -You can verify the samples pass by running `mdbook test`. - -### Linkcheck - -To verify that links are not broken, run `cargo xtask linkcheck`. - -### Running all tests - -As a last step before opening a PR, it is recommended to run `cargo xtask test-all`. This will go through and run most of the tests that are required for CI to pass. See `xtask/src/main.rs` for what all this does. - -## Special markdown constructs - -The following are extensions provided by [`mdbook-spec`](https://github.com/rust-lang/spec/tree/main/mdbook-spec). - -### Rules - -Most clauses should be preceded with a rule. Rules can be specified in the markdown source with the following on a line by itself: - -```markdown -r[foo.bar] -``` - -The rule name should be lowercase, with periods separating from most general to most specific (like `r[array.repeat.zero]`). - -Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are automatic link references so that any rule can be referred to from any page in the book. - -In the HTML, the rules are clickable just like headers. - -When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines: - -1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to. -2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break. - * This content will be moved to `[!NOTE]` or more specific admonitions in the future. -3. Rust code examples and tests do not need their own rules. -4. Use the following guidelines for admonitions: - * Notes: Do not include a rule. - * Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules. - * Target specific behavior: Always include the rule. - * Edition differences: Always include the rule. -5. The following keywords should be used to identify paragraphs when unambiguous: - * `intro`: The beginning paragraph of each section - should explain the construct being defined overall. - * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used. - * `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`). -6. When a rule doesn't fall under the above keywords, or for section rule ids, name the subrule as follows: - * If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s). - * Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule". - * Whenever possible, do not repeat previous components of the rule. - * Edition differences admonitions should typically be named by the edition where the behavior changed. You should be able to correspond the dates to the chapters in . - * Target specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS). - * Use an appropriately descriptive, but short, name if the language does not provide one. - -#### Test rule annotations - -Tests in can be linked to rules in the reference. The rule will include a link to the tests, and there is also an [appendix] which tracks how the rules are currently linked. - -Tests in the `tests` directory can be annotated with the `//@ reference: x.y.z` header to link it to a rule. The header can be specified multiple times if a single file covers multiple rules. - -Compiler developers are not expected to add `reference` annotations to tests. However, if they do want to help, their cooperation is very welcome. Reference authors and editors are responsible for making sure every rule has a test associated with it. - -The tests are beneficial for reviewers to see the behavior of a rule. It is also a benefit to readers who may want to see examples of particular behaviors. When adding new rules, you should wait until the reference side is approved before submitting a PR to `rust-lang/rust` (to avoid churn if we decide on different names). - -Prefixed rule names should not be used in tests. That is, do not use something like `asm.rules` when there are specific rules like `asm.rules.reg-not-input`. - -We are not expecting 100% coverage at any time. Although it would be nice, it is unrealistic due to the sequence things are developed, and resources available. - -[appendix]: https://doc.rust-lang.org/nightly/reference/test-summary.html - -### Standard library links - -You should link to the standard library without specifying a URL in a fashion similar to [rustdoc intra-doc links][intra]. Some examples: - -We can link to the page on `Option`: - -```markdown -[`std::option::Option`] -``` - -In these links, generics are ignored and can be included: - -```markdown -[`std::option::Option`] -``` - -If we don't want the full path in the text, we can write: - -```markdown -[`Option`](std::option::Option) -``` - -Macros can end in `!`. This can be helpful for disambiguation. For example, this refers to the macro rather than the module: - -```markdown -[`alloc::vec!`] -``` - -Explicit namespace disambiguation is also supported: - -```markdown -[`std::vec`](mod@std::vec) -``` - -Beware there are some limitations, for example: - -- Links to rexports from `std_arch` don't work due to . -- Links to keywords aren't supported. -- Links to trait impls where the trait is not in the prelude doesn't work. Traits must be in scope, and there currently isn't a way to add those. -- If there are multiple generic implementations, it will link to one randomly (see ). - -When running into a rustdoc limitation, consider manually linking to the correct page using a relative link. For example, `../std/arch/macro.is_x86_feature_detected.html`. - -[intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html - -### Admonitions - -Admonitions use a style similar to GitHub-flavored markdown, where the style name is placed at the beginning of a blockquote, such as: - -```markdown -> [!WARNING] -> This is a warning. - -> [!NOTE] -> This is a note. - -> [!EDITION-2024] -> This is an edition-specific difference. - -> [!EXAMPLE] -> This is an example. -``` - -The color and styling is defined in [`theme/reference.css`](https://github.com/rust-lang/reference/blob/master/theme/reference.css) and the transformation and icons are in [`mdbook-spec/src/admonitions.rs`](https://github.com/rust-lang/reference/blob/HEAD/mdbook-spec/src/admonitions.rs). - -## Style - -Idioms and styling: - -* Use American English spelling. -* Use Oxford commas. -* Avoid slashes for alternatives ("program/binary"); use conjunctions or rewrite it ("program or binary"). -* Avoid qualifying something as "in Rust"; the entire reference is about Rust. - ## Content guidelines The following are guidelines for the content of the reference. @@ -222,11 +25,3 @@ r[foo.bar.edition2021] > [!EDITION-2021] > Describe what changed in 2021. ``` - -## Grammar - -See [Grammar](grammar.md) for details on how to write grammar rules. - -## Attributes - -See the [attribute template](attribute-template.md) for how attributes should be formatted. diff --git a/reference-dev-guide/README.md b/reference-dev-guide/README.md new file mode 100644 index 0000000000..2daf972ee6 --- /dev/null +++ b/reference-dev-guide/README.md @@ -0,0 +1,7 @@ +# The Rust Reference Developer Guide + +This is the source of the Reference Developer Guide, published at . It is written in Markdown, using the [mdbook] tool to convert to HTML. If you are editing these pages, the best option to view the results is to run `mdbook serve --open`, which will start a web server on localhost that you can visit to view the book, and it will automatically reload each time you edit a page. + +This is published via GitHub Actions to GitHub Pages. + +[mdbook]: https://rust-lang.github.io/mdBook/ diff --git a/reference-dev-guide/book.toml b/reference-dev-guide/book.toml new file mode 100644 index 0000000000..05a532e677 --- /dev/null +++ b/reference-dev-guide/book.toml @@ -0,0 +1,11 @@ +[book] +title = "The Rust Reference Developer Guide" +language = "en" + +[output.html] +git-repository-url = "https://github.com/rust-lang/reference/tree/master/reference-dev-guide" +edit-url-template = "https://github.com/rust-lang/reference/edit/master/reference-dev-guide/{path}" +smart-punctuation = true + +[output.html.search] +use-boolean-and = true diff --git a/reference-dev-guide/src/SUMMARY.md b/reference-dev-guide/src/SUMMARY.md new file mode 100644 index 0000000000..5307a723cc --- /dev/null +++ b/reference-dev-guide/src/SUMMARY.md @@ -0,0 +1,25 @@ +# Summary + +- [Introduction](introduction.md) +- [Contribution process](process/index.md) + - [Stabilization process](process/stabilization.md) +- [Publishing process](publishing.md) +- [Reference tooling](tooling/index.md) + - [Building the Reference](tooling/building.md) + - [mdbook-spec](tooling/mdbook-spec.md) +- [Tests](tests.md) +- [Formatting](formatting/index.md) + - [Markdown](formatting/markdown.md) + - [Admonitions](formatting/admonitions.md) +- [Language rules](rules/index.md) + - [rustc test annotations](rules/test-annotations.md) +- [Examples](examples.md) +- [Links](links.md) +- [Rust grammar](grammar.md) +- [Attributes](attributes.md) +- [Style guide](style/index.md) + - [Wording](style/wording.md) + - [Language and grammar]() + - [Punctuation](style/punctuation.md) +- [Review policy](review-policy.md) +- [Resources](resources.md) diff --git a/docs/attribute-template.md b/reference-dev-guide/src/attributes.md similarity index 75% rename from docs/attribute-template.md rename to reference-dev-guide/src/attributes.md index 07990e501a..02fec36d0e 100644 --- a/docs/attribute-template.md +++ b/reference-dev-guide/src/attributes.md @@ -1,8 +1,8 @@ -# Attribute template +# Attributes Attributes should use the following template. Examples are given for phrasing you *should* use, but you should deviate if the attribute doesn't fit any of the examples or if they get in the way of clarity. -When an attribute (or a new attribute position in the grammar) is added, be sure to update all the "attributes on" sections which list which attributes can be used in various positions. +When an attribute (or a new attribute position in the grammar) is added, be sure to update all the "attributes on" sections that list which attributes can be used in various positions. ---- @@ -11,7 +11,7 @@ r[PARENT.example] ## The `example` attribute r[PARENT.example.intro] -The *`example` [attribute][attributes]* ...give a high level description. +The *`example` [attribute][attributes]* ...give a high-level description. > [!EXAMPLE] > ```rust @@ -22,7 +22,7 @@ The *`example` [attribute][attributes]* ...give a high level description. > ``` r[PARENT.example.syntax] -Describe the accepted syntax of this attribute. You can either explain that it uses one of the pre-existing grammars like `MetaWord` or define an explicit grammar. If there are different forms, briefly describe the syntax here, and link to the appropriate rules below that explain the behavior of the different forms. Examples: +Describe the accepted syntax of this attribute. You can either explain that it uses one of the pre-existing grammars, like `MetaWord`, or define an explicit grammar. If there are different forms, briefly describe the syntax here and link to the appropriate rules below that explain the behavior of the different forms. Examples: ---- @@ -50,7 +50,7 @@ The `example` attribute uses the [MetaNameValueStr] syntax. The value in the str ---- -The `example` attribute has these forms: +The `example` attribute has the following forms: - [MetaWord] > [!EXAMPLE] @@ -92,7 +92,7 @@ The [MetaNameValueStr] form of the `example` attribute provides a way to specify > ``` r[PARENT.example.allowed-positions] -Explain the valid positions where this attribute may be used. +Explain the valid positions where this attribute can be used. See [`check_attr`](https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_passes/src/check_attr.rs) and [`builtin_attrs.rs`](https://github.com/rust-lang/rust/blob/HEAD/compiler/rustc_feature/src/builtin_attrs.rs) in the compiler. Don't forget that some attributes only work as inner or outer attributes. Examples: @@ -110,7 +110,7 @@ The `example` attribute is allowed anywhere attributes are allowed. ---- -If there are unused attribute warnings, or if rustc is incorrectly accepting some positions, include a note about these. +If there are unused attribute warnings, or if `rustc` is incorrectly accepting some positions, include a note about these. > [!NOTE] > `rustc` ignores use in other positions but lints against it. This may become an error in the future. @@ -118,7 +118,7 @@ If there are unused attribute warnings, or if rustc is incorrectly accepting som ---- r[PARENT.example.duplicates] -Explain the behavior if the attribute is specified multiple times on an element. See [`AttributeDuplicates`](https://github.com/rust-lang/rust/blob/40d2563ea200f9327a8cb8b99a0fb82f75a7365c/compiler/rustc_feature/src/builtin_attrs.rs#L143) in the compiler. Examples: +Explain the behavior when the attribute is specified multiple times on an element. See [`AttributeDuplicates`](https://github.com/rust-lang/rust/blob/40d2563ea200f9327a8cb8b99a0fb82f75a7365c/compiler/rustc_feature/src/builtin_attrs.rs#L143) in the compiler. Examples: ---- @@ -160,7 +160,7 @@ If the `example` attribute is used more than once on an item, then the combinati ---- r[PARENT.example.ATTR_NAME] -If this attribute cannot be used with another attribute, specify each one. Do this on both attributes. Example: +If this attribute cannot be used with another attribute, specify each conflicting attribute. Do this for both attributes. Example: ---- @@ -169,7 +169,7 @@ The `example` attribute may not be used with the [`foo`] attribute. ---- r[PARENT.example.unsafe] -If this is an `unsafe` attribute, explain the safety conditions it must uphold. If not, don't include this section. Be sure to also update `attributes.safety` when adding a new unsafe attribute. Example: +If this is an `unsafe` attribute, explain the safety conditions it must uphold. Otherwise, do not include this section. Be sure to also update `attributes.safety` when adding a new unsafe attribute. Example: ---- @@ -178,7 +178,7 @@ The `example` attribute must be marked with [`unsafe`][attributes.safety] becaus ---- r[PARENT.example.stdlib] -This rule explains if the attribute is exported in the standard library. Skip this if it is not. Example: +This rule explains whether the attribute is exported in the standard library. Skip this section if it is not. Example: ---- @@ -187,4 +187,4 @@ The `example` attribute is exported in the standard library prelude as [`core::p ---- r[PARENT.example.foo] -From here on, add rules explaining all the behaviors of the attribute. If the attribute is very simple, you can just have one rule called ".behavior" to explain its behavior. More complex attributes, such as those with multiple kinds of inputs or different modes should describe each as a separate rule. +From here on, add rules explaining all the behaviors of the attribute. If the attribute is very simple, you can just have one rule called `.behavior` to explain its behavior. More complex attributes, such as those with multiple kinds of inputs or different modes, should describe each as a separate rule. diff --git a/reference-dev-guide/src/examples.md b/reference-dev-guide/src/examples.md new file mode 100644 index 0000000000..6c31f7063a --- /dev/null +++ b/reference-dev-guide/src/examples.md @@ -0,0 +1,37 @@ +# Examples + +## Example code blocks + +Code examples should use code blocks with triple backticks. The language should always be specified (such as `rust`). + +```rust +println!("Hello!"); +``` + +See the [mdBook supported languages] for a list of supported languages. + +## rustdoc attributes + +Rust examples are [tested via rustdoc] and should include the appropriate annotations: + +- `edition2015`, `edition2018`, etc. --- Use if it is edition-specific (see `book.toml` for the default). +- `no_run` --- The example should compile successfully but should not be executed. +- `should_panic` --- The example should compile and run but produce a panic. +- `compile_fail` --- The example is expected to fail to compile. +- `ignore` --- The example shouldn't be built or tested. This should be avoided if possible. Usually, this is only necessary when the testing framework does not support it (such as external crates, modules, or a proc-macro) or when it contains pseudo-code that is not valid Rust. An HTML comment, such as ``, should be placed before the example to explain why it is ignored. +- `Exxxx` --- If the example is expected to fail to compile with a specific error code, include that code so that `rustdoc` checks that the expected code is used. + +See the [rustdoc documentation] for more detail. + +## Combining examples + +When demonstrating success cases, multiple cases may be included in a single code block. For failure cases, however, each example must appear in a separate code block so that the tests can ensure that each case indeed fails with the appropriate error code. + +## Testing examples + +The Rust code blocks are tested in CI. You can verify that the samples pass by running [`mdbook test`]. + +[`mdbook test`]: tests.md#inline-tests +[mdBook supported languages]: https://rust-lang.github.io/mdBook/format/theme/syntax-highlighting.html#supported-languages +[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html +[tested via rustdoc]: tests.md#inline-tests diff --git a/reference-dev-guide/src/formatting/admonitions.md b/reference-dev-guide/src/formatting/admonitions.md new file mode 100644 index 0000000000..db18339fa7 --- /dev/null +++ b/reference-dev-guide/src/formatting/admonitions.md @@ -0,0 +1,23 @@ +# Admonitions + +[`mdbook-spec`](../tooling/mdbook-spec.md) provides admonitions which use a style similar to GitHub-flavored markdown. The style name is placed at the beginning of a blockquote, such as: + +```markdown +> [!WARNING] +> This is a warning. + +> [!NOTE] +> This is a note. + +> [!EDITION-2024] +> This is an edition-specific difference. + +> [!EXAMPLE] +> This is an example. +``` + +The color and styling is defined in [`theme/reference.css`](https://github.com/rust-lang/reference/blob/master/theme/reference.css) and the transformation and icons are in [`mdbook-spec/src/admonitions.rs`](https://github.com/rust-lang/reference/blob/HEAD/mdbook-spec/src/admonitions.rs). + +See the [conventions section] for a description of how these should be used. + +[conventions section]: https://doc.rust-lang.org/nightly/reference/#conventions diff --git a/reference-dev-guide/src/formatting/index.md b/reference-dev-guide/src/formatting/index.md new file mode 100644 index 0000000000..58b739bfc3 --- /dev/null +++ b/reference-dev-guide/src/formatting/index.md @@ -0,0 +1,3 @@ +# Formatting + +The following chapters detail how the Reference source should be formatted. diff --git a/reference-dev-guide/src/formatting/markdown.md b/reference-dev-guide/src/formatting/markdown.md new file mode 100644 index 0000000000..aa42bd1946 --- /dev/null +++ b/reference-dev-guide/src/formatting/markdown.md @@ -0,0 +1,45 @@ +# Markdown + +There are automated checks for some of these rules. Run [`cargo xtask style-check`] to run them locally. + +## Formatting style + +- Use [ATX-style headings][atx] (not Setext) with [sentence case]. +- Do not use tabs; use only spaces. +- Files must end with a newline. +- Lines must not end with spaces. Double spaces have semantic meaning but can be invisible. Use a trailing backslash if you need a hard line break. +- If possible, avoid double blank lines. +- Do not wrap long lines. This helps with reviewing diffs of the source. +- Use [smart punctuation] instead of Unicode characters. For example, use `---` for an em-dash instead of the Unicode character. Characters like the em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters. +- See the [admonitions chapter] for formatting callouts such as notes, edition differences, and warnings. + +## Code blocks + +- Do not use indented code blocks; use fenced code blocks with 3+ backticks instead. +- Code blocks should have an explicit language tag. + +## Links + +See the [links chapter] for more information about linking. + +- Links to other chapters should be relative and use the `.md` extension. +- Links to other rust-lang books that are published with the Reference should also be relative so that the linkchecker can validate them. See [outside book links]. +- Links to the standard library should use rustdoc-style links as described in [standard library links]. +- The use of reference links is preferred, with shortcuts if appropriate. Place sorted link reference definitions at the bottom of the file, or at the bottom of a section if there is an unusually large number of links specific to that section. + + ```markdown + Example of shortcut link: [enumerations] + Example of reference link with label: [block expression][block] + + [block]: expressions/block-expr.md + [enumerations]: types/enum.md + ``` + +[`cargo xtask style-check`]: ../tests.md#style-checks +[admonitions chapter]: admonitions.md +[atx]: https://spec.commonmark.org/0.31.2/#atx-headings +[links chapter]: ../links.md +[outside book links]: ../links.md#outside-book-links +[sentence case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case +[smart punctuation]: https://rust-lang.github.io/mdBook/format/markdown.html#smart-punctuation +[standard library links]: ../links.md#standard-library-links diff --git a/docs/grammar.md b/reference-dev-guide/src/grammar.md similarity index 50% rename from docs/grammar.md rename to reference-dev-guide/src/grammar.md index 190782bba4..bc6fbb58aa 100644 --- a/docs/grammar.md +++ b/reference-dev-guide/src/grammar.md @@ -1,8 +1,8 @@ -# Grammar +# Rust grammar -The Reference grammar is written in markdown code blocks using a modified BNF-like syntax (with a blend of regex and other arbitrary things). The `mdbook-spec` extension parses these rules and converts them to a renderable format, including railroad diagrams. +The Reference grammar is written in markdown code blocks using a modified BNF-like syntax (with a blend of regex and other arbitrary things). The [`mdbook-spec`] extension parses these rules and converts them into a renderable format, including railroad diagrams. -The code block should have a lang string with the word "grammar", a comma, and the category of the grammar, like this: +The code block should have a lang string with the word `grammar`, a comma, and the category of the grammar, like this: ~~~ ```grammar,items @@ -14,7 +14,7 @@ The category is used to group similar productions on the grammar summary page in ## Grammar syntax -The syntax for the grammar itself is pretty close to what is described in the [Notation chapter](../src/notation.md), though there are some rendering differences. +The syntax for the grammar itself is similar to what is described in the [Notation chapter], though there are some rendering differences. A "root" production, marked with `@root`, is one that is not used in any other production. @@ -94,35 +94,38 @@ Group -> `(` ` `* Expression ` `* `)` NegativeExpression -> `~` ( Charset | Terminal | NonTerminal ) ``` -The general format is a series of productions separated by blank lines. The expressions are: +The general format is a series of productions separated by blank lines. The expressions are as follows: | Expression | Example | Description | |------------|---------|-------------| -| Unicode | U+0060 | A single unicode character. | +| Unicode | U+0060 | A single Unicode character. | | NonTerminal | FunctionParameters | A reference to another production by name. | -| Break | | This is used internally by the renderer to detect line breaks and indentation. | +| Break | | Used internally by the renderer to detect line breaks and indentation. | | Comment | // Single line comment. | A comment extending to the end of the line. | -| Terminal | \`example\` | This is a sequence of exact characters, surrounded by backticks | -| Charset | [ \`A\`-\`Z\` \`0\`-\`9\` \`_\` ] | A choice from a set of characters, space separated. There are three different forms. | -| CharacterRange | [ \`A\`-\`Z\` ] | A range of characters, each character should be in backticks. -| CharacterTerminal | [ \`x\` ] | A single character, surrounded by backticks. | -| CharacterName | [ LF ] | A nonterminal, referring to another production. | -| Prose | \ | This is an English description of what should be matched, surrounded in angle brackets. | -| Group | (\`,\` Parameter)+ | This groups an expression for the purpose of precedence, such as applying a repetition operator to a sequence of other expressions. -| NegativeExpression | ~[\` \` LF] | Matches anything except the given Charset, Terminal, or Nonterminal. | -| Sequence | \`fn\` Name Parameters | A sequence of expressions, where they must match in order. | +| Terminal | \`example\` | A sequence of exact characters, surrounded by backticks. | +| Charset | \[ \`A\`-\`Z\` \`0\`-\`9\` \`_\` \] | A choice from a set of characters, space-separated. There are three different forms. | +| CharacterRange | \[ \`A\`-\`Z\` \] | A range of characters; each character should be in backticks. +| CharacterTerminal | \[ \`x\` \] | A single character, surrounded by backticks. | +| CharacterName | \[ LF \] | A nonterminal, referring to another production. | +| Prose | \ | An English description of what should be matched, surrounded in angle brackets. | +| Group | (\`,\` Parameter)+ | Groups an expression for the purpose of precedence, such as applying a repetition operator to a sequence of other expressions. +| NegativeExpression | ~\[\` \` LF\] | Matches anything except the given Charset, Terminal, or Nonterminal. | +| Sequence | \`fn\` Name Parameters | A sequence of expressions that must match in order. | | Alternation | Expr1 \| Expr2 | Matches only one of the given expressions, separated by the vertical pipe character. | -| Suffix | \_except \[LazyBooleanExpression\]\_ | This adds a suffix to the previous expression to provide an additional English description to it, rendered in subscript. This can have limited markdown, but try to avoid anything except basics like links. | -| Footnote | \[^extern-safe\] | This adds a footnote, which can supply some extra information that may be helpful to the user. The footnote itself should be defined outside of the code block like a normal markdown footnote. | +| Suffix | \_except \[LazyBooleanExpression\]\_ | Adds a suffix to the previous expression to provide an additional English description, rendered in subscript. This can contain limited markdown, but try to avoid anything except basics like links. | +| Footnote | \[^extern-safe\] | Adds a footnote, which can supply extra information that may be helpful to the user. The footnote itself should be defined outside of the code block like a normal markdown footnote. | | Optional | Expr? | The preceding expression is optional. | | Repeat | Expr* | The preceding expression is repeated 0 or more times. | | Repeat (non-greedy) | Expr*? | The preceding expression is repeated 0 or more times without being greedy. | | RepeatPlus | Expr+ | The preceding expression is repeated 1 or more times. | | RepeatPlus (non-greedy) | Expr+? | The preceding expression is repeated 1 or more times without being greedy. | -| RepeatRange | Expr{2..4} | The preceding expression is repeated between the range of times specified. Either bounds can be excluded, which works just like Rust ranges. | +| RepeatRange | Expr{2..4} | The preceding expression is repeated between the range of times specified. Either bound can be excluded, which works just like Rust ranges. | ## Automatic linking -The plugin automatically adds markdown link definitions for all the production names on every page. If you want to link directly to a production name, all you need to do is surround it in square brackets, like `[ArrayExpression]`. +The [`mdbook-spec`] plugin automatically adds markdown link definitions for all production names on every page. To link directly to a production name, simply surround it in square brackets, like `[ArrayExpression]`. -In some cases there might be name collisions with the automatic linking of rule names. In that case, disambiguate with the `grammar-` prefix, such as `[Type][grammar-Type]`. You can also do that if you just feel like being more explicit. +In some cases, there might be name collisions with the automatic linking of rule names. In that case, disambiguate with the `grammar-` prefix, such as `[Type][grammar-Type]`. You can also do this if you prefer to be more explicit. + +[`mdbook-spec`]: tooling/mdbook-spec.md +[Notation chapter]: https://doc.rust-lang.org/nightly/reference/notation.html diff --git a/reference-dev-guide/src/introduction.md b/reference-dev-guide/src/introduction.md new file mode 100644 index 0000000000..8190842eb1 --- /dev/null +++ b/reference-dev-guide/src/introduction.md @@ -0,0 +1,38 @@ +# Introduction + +Thank you for your interest in contributing to the Rust Reference! This guide provides an overview of how to contribute to the Reference, and serves as a guide for editors and reviewers. + +There are a few ways of helping with the Reference: critiquing the Reference, editing the Reference, fixing incorrect information, adding examples and glossary entries, and documenting new or otherwise undocumented features in Rust. + +It is encouraged for you to read the [introduction] of the Reference to familiarize yourself with the kind of content the Reference is expected to contain and the conventions it uses. + +## Critiquing the Reference + +This is the easiest way to contribute. As you read the Reference, if you find something confusing, incorrect, or missing, then you can file an issue against the Reference explaining your concerns. + +## Editing the Reference + +Typos and incorrect links get through from time to time. Should you find them, we welcome PRs to fix them. + +## Adding examples and glossary entries + +Examples are great. Many people will only read examples and ignore the prose. Ideally, every facet of every feature should have an example. + +Likewise, the Reference has a glossary. It doesn't need to explain every facet of every feature nor contain every definition, but it does need to be expanded upon. Ideally, entries in the glossary should link to the associated documentation. + +## Adding documentation + +There are a lot of features that are not documented at all or are documented poorly. This is the hardest task, but definitely the most valuable. Pick an unassigned issue from the [issue tracker], and write about it. + +While writing, you may find it handy to have a [playground] open to test out what you are documenting. + +Feel free to take information from the standard library and Rustonomicon as appropriate. + +Note that we don't write documentation for purely library features, such as threads and IO, and we don't write about Rust in the future. Documentation is written as if the current stable release of Rust is the last release. The `master` branch of the Reference corresponds to what is **stable** on the `master` branch ("nightly") of [rust-lang/rust]. If you want to write about Rust in the future, you want [the Unstable book][unstable]. + +[Authoring Guide]: docs/authoring.md +[introduction]: https://doc.rust-lang.org/nightly/reference/introduction.html +[issue tracker]: https://github.com/rust-lang/reference/issues +[playground]: https://play.rust-lang.org/ +[rust-lang/rust]: https://github.com/rust-lang/rust/ +[unstable]: https://doc.rust-lang.org/nightly/unstable-book/ diff --git a/reference-dev-guide/src/links.md b/reference-dev-guide/src/links.md new file mode 100644 index 0000000000..d977e19b7f --- /dev/null +++ b/reference-dev-guide/src/links.md @@ -0,0 +1,97 @@ +# Links + +This chapter explains how links should be handled by the Reference. Several of these capabilities are provided by [`mdbook-spec`](tooling/mdbook-spec.md). + +See also the [linkchecker tests](tests.md#linkcheck) for testing links. + +## Rule links + +[Rules](rules/index.md) can be linked to by their ID using Markdown, with the destination set to the rule ID. Automatic link references allow any rule to be referred to from any page in the book. + +```markdown +Direct label link: [names.preludes.lang] + +Destination label link (custom link text): [language prelude][names.preludes.lang] + +Definition link: [namespace kinds] + +[namespace kinds]: names.namespaces.kinds +``` + +## Standard library links + +You should link to the standard library without specifying a URL, in a fashion similar to [rustdoc intra-doc links][intra]. Some examples: + +We can link to the page on `Option`: + +```markdown +[`std::option::Option`] +``` + +In these links, generics are ignored and can be included: + +```markdown +[`std::option::Option`] +``` + +If we don't want the full path in the text, we can write: + +```markdown +[`Option`](std::option::Option) +``` + +Macros can end in `!`. This can be helpful for disambiguation. For example, this refers to the macro rather than the module: + +```markdown +[`alloc::vec!`] +``` + +Explicit namespace disambiguation is also supported: + +```markdown +[`std::vec`](mod@std::vec) +``` + +Beware of some limitations, for example: + +- Links to re-exports from `std_arch` don't work due to . +- Links to keywords aren't supported. +- Links to trait impls where the trait is not in the prelude don't work. Traits must be in scope, and currently there is no way to add them. +- If there are multiple generic implementations, it will link to one randomly (see ). + +When running into a rustdoc limitation, consider manually linking to the correct page using a relative link. For example, `../std/arch/macro.is_x86_feature_detected.html`. + +When rendering the Reference locally, it uses relative links by default to conform with how the books are published. This probably isn't what you want, so you will usually want to set the [`SPEC_RELATIVE=0` environment variable][rel] so that the links go to the live site instead. + +[intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html +[rel]: tooling/building.md#spec_relative + +## Grammar links + +Link definitions are automatically generated for all grammar production names. See [grammar automatic linking](grammar.md#automatic-linking) for more. + +```markdown +This attribute uses the [MetaWord] syntax. + +Explicit grammar links can have the `grammar-` prefix like [Type][grammar-Type]. +``` + +## Outside book links + +Links to other books published with the Reference should be relative links pointing to the corresponding book. This allows the links to point to the correct version, to work with the offline docs, and to be checked by the linkchecker. For example: + +```markdown +See [`-C panic`]. + +[`-C panic`]: ../rustc/codegen-options/index.html#panic +``` + +## Internal links + +When possible, internal links should use [rule links](#rule-links) or [grammar links](#grammar-links). Otherwise, links should be relative to the file path and use the `.md` extension. + +```markdown +- Rule link: [language prelude][names.preludes.lang] +- Grammar link: [MetaWord] +- Internal link: [Modules](items/modules.md#attributes-on-modules) +``` diff --git a/reference-dev-guide/src/process/index.md b/reference-dev-guide/src/process/index.md new file mode 100644 index 0000000000..7af8391953 --- /dev/null +++ b/reference-dev-guide/src/process/index.md @@ -0,0 +1,80 @@ +# Contribution process + +## Before contributing + +We encourage people to discuss their changes before opening a PR. This gives the Reference team a chance to understand your idea better and ensure it fits with the intended direction of the Reference. Typically, you should file an issue or start a thread on [Zulip](#zulip) before submitting a pull request. + +## Contributing process overview + +The general outline of a contribution is as follows: + +1. [Check out the source.](../tooling/building.md#checking-out-the-source) +2. [Install mdbook.](../tooling/building.md#installing-mdbook) +3. [Learn to build the book locally.](../tooling/building.md#running-mdbook) +4. Make your changes to the source files. Be sure to follow all the guidelines in this book for styling, conventions, etc. +5. [Run the tests.](../tests.md) +6. [Submit a pull request](#submitting-a-pull-request) +7. The PR will go through the review process. + - There is a [guide](../review-policy.md) for the types of reviews it may undergo. + - This may take a while, as the team has limited time. +8. Once approved, a team member will merge the change. + - The team may apply editorial changes before merging. + - It may take a few weeks for the change to appear on the [nightly website](https://doc.rust-lang.org/nightly/reference/). See [the publishing chapter](../publishing.md) for more details. + +## Office hours + +The lang-docs team holds office hours on Tuesdays at [3:30 PM US/Eastern](https://dateful.com/convert/est-edt-eastern-time?t=330pm). We meet on [Jitsi Meet](https://meet.jit.si/rust-t-lang-docs). Check the [Zulip](#zulip) channel for the latest status and availability. + +## Zulip + +There are channels on Zulip for more direct discussions about the Reference: + +- [`#t-lang-docs`](https://rust-lang.zulipchat.com/#narrow/channel/237824-t-lang-docs) --- Used by the lang docs team. +- [`#t-lang-docs/reference`](https://rust-lang.zulipchat.com/#narrow/channel/520709-t-lang-docs.2Freference) --- Discussion about the Reference specifically. + +## Working on issues + +Issues labeled with [Help Wanted] are ones the team wants to see addressed and is asking for contributions. + +If you want to work on an issue, you can assign yourself by commenting `@rustbot claim`. See [issue assignment] for more information. + +[Help Wanted]: https://github.com/rust-lang/reference/issues?q=state%3Aopen%20label%3A%22Help%20Wanted%22 +[issue assignment]: https://forge.rust-lang.org/triagebot/issue-assignment.html + +## New features + +See the [stabilization chapter] for information on how to document new features. + +[stabilization chapter]: stabilization.md + +## Minor changes + +Minor changes, like small corrections, wording cleanup, or formatting fixes, can be made simply by opening a PR. + +## Major changes + +Major changes, such as large rewrites, reorganization, or new chapters, should be approved by the Reference team first. Open an issue (if there isn't already one) to discuss the kinds of changes you are interested in. If the Reference team is able, they can work with you to approve the change. + +## Submitting a pull request + +When submitting a pull request, please follow these guidelines: + +- Include a clear description of what the change is and why it is being made. +- Try to keep a clean git history, with each commit explaining the reason for the change. +- Use [GitHub’s keywords] in the description to automatically link to an issue if the PR resolves it. For example, `Closes #1234` will link issue #1234 to the PR. When the PR is merged, GitHub will automatically close the issue. + +When your PR is submitted, GitHub automatically runs all tests. The GitHub interface shows a green checkmark if it passes, or a red X if it fails. Links to the logs are available on the PR page to diagnose any issues. + +[GitHub’s keywords]: https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue + +### PR labeling + +PRs are marked with [labels] like [`S-waiting-on-review`] or [`S-waiting-on-author`] to indicate their status. Anyone can use the [`@rustbot`] bot to adjust the labels. If a PR is marked as `S-waiting-on-author` and you have pushed new changes that you would like reviewed, you can comment on the PR with `@rustbot ready`. The bot will switch the labels on the PR. + +More information about these commands can be found at the [shortcuts documentation]. + +[`@rustbot`]: https://github.com/rustbot +[`S-waiting-on-author`]: https://github.com/rust-lang/reference/labels/S-waiting-on-author +[`S-waiting-on-review`]: https://github.com/rust-lang/reference/labels/S-waiting-on-review +[labels]: https://github.com/rust-lang/reference/labels +[shortcuts documentation]: https://forge.rust-lang.org/triagebot/shortcuts.html diff --git a/reference-dev-guide/src/process/stabilization.md b/reference-dev-guide/src/process/stabilization.md new file mode 100644 index 0000000000..f70d64fe8f --- /dev/null +++ b/reference-dev-guide/src/process/stabilization.md @@ -0,0 +1,24 @@ +# Stabilization process + +New features and changes to the Rust language usually require an update to the Reference to incorporate the change. This can be done at any time before stabilization, and it is usually better to prepare a PR early (assuming the implementation is not expected to change significantly). + +An exception to this process occurs when a language change involves a section of the Reference or language that is undocumented. For example, type inference is currently not documented, so changes to it do not require an update to the Reference. + +## Pull request + +When opening a PR, please include links to as much information as possible so that reviewers can better understand the change. This includes links to the following, if they exist: + +- The tracking issue. +- The `rust-lang/rust` stabilization pull request. +- The stabilization report. +- Background information such as RFCs. +- The files in `rustc` where it is implemented, if it is isolated to a relatively concise part. +- The tests in `rust-lang/rust`. + +Some of this information may already exist, such as in the tracking issue, stabilization report, or PR, so there is no need to duplicate it. + +## Inline tests + +Because the Reference only documents stabilized features, inline tests will fail. We intend to improve this process in the future (see [#1864]). + +[#1864]: https://github.com/rust-lang/reference/issues/1864 diff --git a/reference-dev-guide/src/publishing.md b/reference-dev-guide/src/publishing.md new file mode 100644 index 0000000000..26edd0f60b --- /dev/null +++ b/reference-dev-guide/src/publishing.md @@ -0,0 +1,11 @@ +# Publishing process + +The process for getting the Reference content into a [Rust release](https://doc.rust-lang.org/reference/#rust-releases) and on the website is as follows: + +1. Changes are merged to this repository. +2. [Triagebot](https://forge.rust-lang.org/triagebot/doc-updates.html) will automatically synchronize this repository to [rust-lang/rust]. This happens every other week. The reference is tracked in [rust-lang/rust] as a [submodule](https://github.com/rust-lang/rust/tree/master/src/doc). + - This will open a PR on [rust-lang/rust] that needs to be merged, which can take up to several days. +3. At midnight UTC, whatever is on the default branch of [rust-lang/rust] will be part of that nightly release and will be published after a few hours to . +4. Following Rust's [release process](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html), every 6 weeks, nightly is promoted to beta (), and 6 weeks after that, it is promoted to stable (). + +[rust-lang/rust]: https://github.com/rust-lang/rust/ diff --git a/reference-dev-guide/src/resources.md b/reference-dev-guide/src/resources.md new file mode 100644 index 0000000000..0c70c04b66 --- /dev/null +++ b/reference-dev-guide/src/resources.md @@ -0,0 +1,6 @@ +# Resources + +The Reference team has collected a set of resources about language specifications and technical writing. + +- [Language specs](https://hackmd.io/@rust-spec-team/HJey-puL6) --- It can be very useful to become familiar with how other languages are specified. This includes papers, standards, and commentary on how languages are specified. +- [Style and writing guides](https://hackmd.io/@rust-spec-team/rkj1RS3uR) --- This contains a large list of different English and technical writing guides. diff --git a/docs/review-policy.md b/reference-dev-guide/src/review-policy.md similarity index 50% rename from docs/review-policy.md rename to reference-dev-guide/src/review-policy.md index 2195c4440c..4613a167f0 100644 --- a/docs/review-policy.md +++ b/reference-dev-guide/src/review-policy.md @@ -1,29 +1,36 @@ -Team members are given permission to merge changes from other contributors in the repository. There are different guidelines for reviewing based on the kind of changes being made: +# Review policy + +Team members have permission to merge changes from other contributors in the repository. There are different guidelines for reviewing based on the kind of changes being made: ## Review principles Reviewers and authors should focus on a few key principles during the review process: -* **Understandability**: Language within the Reference should be understandable to most members of the Project. Contributions should assumes that readers are familiar with the rest of the content of the Reference, but, wherever possible, sections should facilitate that understanding by linking to related content. +* **Understandability**: Language within the Reference should be understandable to most members of the Project. Contributions should assume that readers are familiar with the rest of the content of the Reference, but, wherever possible, sections should facilitate that understanding by linking to related content. * **Defensibility**: When the lang-docs team merges a change to the Reference, they are agreeing to take responsibility for it going forward. Team members need to feel confident defending and explaining the correctness of content within the Reference. Whenever possible, changes to the Reference should back up any claims with concise examples to verify correctness. -* **Voice**: Authors are not expected to have competence as a specification writer when drafting new contributions to the Reference. So long as claims are understandable and defensible, it is fine for PRs to be written in a casual tone or with the voice of the author instead of the voice of the Reference. Team members will bring editorial experience as part of their reviews and will revise the phrasing, organization, style, etc. to fit the Reference before merging if necessary. +* **Voice**: Authors are not expected to have competence as a specification writer when drafting new contributions to the Reference. As long as claims are understandable and defensible, it is fine for PRs to be written in a casual tone or with the voice of the author instead of the voice of the Reference. Team members will bring editorial experience as part of their reviews and will revise the phrasing, organization, style, etc., to fit the Reference before merging if necessary. ## Policy changes -- Significant changes to the policy of how the team operates, such as changes to this document, should have agreement of the team without any blocking objections. -- Minor changes to something like the style enforcement can be made with the review of a team member, as long as there is high confidence that it is unlikely any team member would object (for example, codifying a guideline that is already in practice), and that the change can be easily reversed. +Significant changes to the policy of how the team operates, such as changes to this document, should have the agreement of the team without any blocking objections. + +Minor changes to something like style enforcement can be made with the review from a team member, as long as there is high confidence that it is unlikely any team member would object (for example, codifying a guideline that is already in practice) and that the change can be easily reversed. ## Meaningful content addition or changes -- When adding or changing content in the spec, the reviewer should consult with appropriate experts to validate the changes. This may not be required if the reviewer has high confidence that the changes are correct, and consider themselves well-versed enough in the topic to understand it, or the relevant experts are the author or have been heavily involved in the process. It is up to the reviewer to use their best judgement when to consult. -- Content should always follow the guidelines from the [authoring guide]. +When adding or changing content in the spec, the reviewer should consult with appropriate experts to validate the changes. This may not be required if the reviewer has high confidence that the changes are correct and considers themselves well-versed enough in the topic to understand it, or if the relevant experts are the author or have been heavily involved in the process. It is up to the reviewer to use their best judgment on when to consult. + +Content should always follow the guidelines in this contributor guide. ## Minor content changes -- Minor content changes, such as small cleanups or wording fixes, can be made with the review from a team member without further consultation. + +Minor content changes, such as small cleanups or wording fixes, can be made with the review from a team member without further consultation. ## Tooling changes -- Minor changes to the tooling may be made with a review from a team member. This includes bug fixes, minor additions that are unlikely to have objections, and additions that have already been discussed. -- Major changes, such as a change in how content is authored, or major changes to how the tooling works should be approved by the team without blocking objections. + +Minor changes to the tooling may be made with a review from a team member. This includes bug fixes, minor additions that are unlikely to have objections, and additions that have already been discussed. + +Major changes, such as a change in how content is authored or major changes to how the tooling works, should be approved by the team without blocking objections. ## Review process flowchart @@ -47,9 +54,7 @@ Some PRs try to "sell" the language too much, or try to explain more (or less) t ### Is this well written? -Some PRs are right but are awkwardly worded or have typographical problems. If the changes are small, we'll just add commits to the branch to clean things up, then merge. +Some PRs are correct but are awkwardly worded or have typographical problems. If the changes are small, we'll just add commits to the branch to clean things up, then merge. This policy does not yet cover the process for getting final approval from the relevant teams. - -[authoring guide]: authoring.md diff --git a/reference-dev-guide/src/rules/index.md b/reference-dev-guide/src/rules/index.md new file mode 100644 index 0000000000..ad2af6b62c --- /dev/null +++ b/reference-dev-guide/src/rules/index.md @@ -0,0 +1,44 @@ +# Language rules + +Clauses within the Reference are labeled with a named *rule*. This provides the ability to link and refer to individual clauses, and to [link to the `rustc` test suite](test-annotations.md). + +## Rule labels + +Most clauses should be preceded by a rule label. A rule label should be on a line by itself, and should look like this: + +```markdown +r[foo.bar] +``` + +The rule name should be lowercase, with periods separating components from most general to most specific (like `r[array.repeat.zero]`). + +Rules can be linked to by their ID using Markdown such as `[foo.bar]`. There are [automatic link references] so that any rule can be referred to from any page in the book. + +In the HTML, the rules are clickable, just like headers. + +## Rule guidelines + +When assigning rules to new paragraphs or modifying rule names, use the following guidelines: + +1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to. +2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous one, separate it with a hard (rendered) line break. + - This content will be moved to `[!NOTE]` or more specific admonitions in the future. +3. Rust code examples and tests do not need their own rules. +4. Use the following guidelines for admonitions: + - Notes: Do not include a rule. + - Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules. + - Target-specific behavior: Always include the rule. + - Edition differences: Always include the rule. +5. The following keywords should be used to identify paragraphs when unambiguous: + - `intro`: The beginning paragraph of each section. It should explain the construct being defined overall. + - `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used. + - `namespace`: For items only, specifies the namespace(s) the item introduces a name in. It may also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`). +6. When a rule doesn't fall under the above keywords, or for section rule IDs, name the subrule as follows: + - If the rule names a specific Rust language construct (e.g., an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s). + - Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule". + - Whenever possible, do not repeat previous components of the rule. + - Edition differences admonitions should typically be named by the edition where the behavior changed. You should be able to correspond the dates to the chapters in . + - Target-specific admonitions should typically be named by the least specific target property to which they apply (e.g., if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686`, and `x86_64`. If a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS). + - Use an appropriately descriptive, but short, name if the language does not provide one. + +[automatic link references]: ../links.md#rule-links diff --git a/reference-dev-guide/src/rules/test-annotations.md b/reference-dev-guide/src/rules/test-annotations.md new file mode 100644 index 0000000000..c641c2a1fd --- /dev/null +++ b/reference-dev-guide/src/rules/test-annotations.md @@ -0,0 +1,15 @@ +# rustc test annotations + +Tests in can be linked to rules in the Reference. The rule will include a link to the tests, and there is also an [appendix] which tracks how the rules are currently linked. + +Tests in the `tests` directory can be annotated with the `//@ reference: x.y.z` header to link them to a rule. The header can be specified multiple times if a single file covers multiple rules. + +Compiler developers are not expected to add `reference` annotations to tests. However, if they do want to help, their cooperation is very welcome. Reference authors and editors are responsible for ensuring every rule has a test associated with it. + +The tests are beneficial for reviewers to see the behavior of a rule. They are also a benefit to readers who may want to see examples of particular behaviors. When adding new rules, you should wait until the Reference side is approved before submitting a PR to `rust-lang/rust` (to avoid churn if we decide on different names). + +Prefixed rule names should not be used in tests. That is, do not use something like `asm.rules` when there are specific rules like `asm.rules.reg-not-input`. + +We do not expect 100% coverage at any time. Although it would be nice, it is unrealistic due to the sequence in which things are developed and the resources available. + +[appendix]: https://doc.rust-lang.org/nightly/reference/test-summary.html diff --git a/reference-dev-guide/src/style/index.md b/reference-dev-guide/src/style/index.md new file mode 100644 index 0000000000..2c18cf82b2 --- /dev/null +++ b/reference-dev-guide/src/style/index.md @@ -0,0 +1,3 @@ +# Style guide + +The following chapters are the preferred style guide for English prose in the Reference. diff --git a/reference-dev-guide/src/style/punctuation.md b/reference-dev-guide/src/style/punctuation.md new file mode 100644 index 0000000000..cba6be2016 --- /dev/null +++ b/reference-dev-guide/src/style/punctuation.md @@ -0,0 +1,5 @@ +# Punctuation + +Use Oxford commas. + +Avoid slashes for alternatives ("program/binary"); use conjunctions or rewrite it ("program or binary"). diff --git a/reference-dev-guide/src/style/wording.md b/reference-dev-guide/src/style/wording.md new file mode 100644 index 0000000000..26a6b26e4f --- /dev/null +++ b/reference-dev-guide/src/style/wording.md @@ -0,0 +1,5 @@ +# Wording + +Use American English spelling. + +Avoid qualifying something as "in Rust"; the entire Reference is about Rust. diff --git a/reference-dev-guide/src/tests.md b/reference-dev-guide/src/tests.md new file mode 100644 index 0000000000..4cbcd4e574 --- /dev/null +++ b/reference-dev-guide/src/tests.md @@ -0,0 +1,60 @@ +# Running tests + +There are several different kinds of tests you can run (these are enforced in CI): + +- [`cargo xtask test-all`](#all-tests) --- Runs all tests. +- [`mdbook test`](#inline-tests) --- Tests the inline Rust codeblocks. +- [`cargo xtask linkcheck`](#linkcheck) --- Validates that markdown links aren't broken. +- [`cargo xtask style-check`](#style-checks) --- Validates various style checks. +- [Code formatting](#code-formatting) --- Checks that all Rust tooling code is formatted. +- [mdbook-spec tests](#mdbook-spec-tests) --- Internal tests for `mdbook-spec`. + +## All tests + +```sh +cargo xtask test-all +``` + +This command runs all the tests listed below. + +We recommend running this as a last step before opening a PR. This runs most of the tests required for CI to pass. See [`xtask/src/main.rs`](https://github.com/rust-lang/reference/blob/master/xtask/src/main.rs) for details on what this does. + +## Inline tests + +```sh +mdbook test +``` + +This command runs all tests that are inline in the Markdown. Internally, this uses [`rustdoc`](https://doc.rust-lang.org/rustdoc/) to run the tests and supports all the same features. Any code block with the `rust` language will be compiled unless it is ignored. See the [Examples chapter](examples.md) for more. + +## Linkcheck + +```sh +cargo xtask linkcheck +``` + +This command verifies that links are not broken. It downloads and uses the [`linkchecker`](https://github.com/rust-lang/rust/tree/main/src/tools/linkchecker) script hosted in the `rust-lang/rust` repository. + +This requires a recent nightly installed via `rustup` and the `rust-docs` component. + +After compiling the script, it builds the Reference using `mdbook` and then scans all local links to verify that they are valid, particularly between various books. This does not check any network links. + +## Style checks + +```sh +cargo xtask style-check +``` + +This uses the [`style-check`](https://github.com/rust-lang/reference/tree/master/style-check) tool to enforce various formatting rules. + +## Code formatting + +CI uses `cargo fmt --check` to verify that all Rust sources for the tools (like `mdbook-spec`) are properly formatted. All code must be formatted with `rustfmt`. + +## mdbook-spec tests + +```sh +cargo test --manifest-path mdbook-spec/Cargo.toml +``` + +CI runs `cargo test` on `mdbook-spec` to execute any tests for the tool itself. diff --git a/reference-dev-guide/src/tooling/building.md b/reference-dev-guide/src/tooling/building.md new file mode 100644 index 0000000000..d02ce7b930 --- /dev/null +++ b/reference-dev-guide/src/tooling/building.md @@ -0,0 +1,64 @@ +# Building the Reference + +## Checking out the source + +To build the Reference, first clone the project: + +```sh +git clone https://github.com/rust-lang/reference.git +cd reference +``` + +## Installing mdbook + +The Reference is built using [mdbook]. + +First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed to run the tests: + +```sh +rustup toolchain install nightly +rustup override set nightly +``` + +Now, ensure you have `mdbook` installed, as this is needed to build the Reference: + +```sh +cargo install --locked mdbook +``` + +[mdbook]: https://rust-lang.github.io/mdBook/ + +## Running mdbook + +`mdbook` provides a variety of commands and options to help you work on the book: + +- `mdbook build --open`: Builds the book and opens it in a web browser. +- `mdbook serve --open`: Launches a web server on localhost. It automatically rebuilds the book whenever any file changes and reloads your web browser. + +The book contents are driven by a `SUMMARY.md` file, and every file must be linked there. See for its usage. + +### `SPEC_RELATIVE` + +The `SPEC_RELATIVE=0` environment variable makes links to the standard library go to instead of being relative. This is useful when viewing locally since you normally don't have a copy of the standard library. + +```sh +SPEC_RELATIVE=0 mdbook serve --open +``` + +The published site at (or local docs using `rustup doc`) does not set this, which means it uses relative links. This supports offline viewing and links to the correct version (for example, links in will stay within the 1.81.0 directory). + +### `SPEC_DENY_WARNINGS` + +The `SPEC_DENY_WARNINGS=1` environment variable turns all warnings generated by `mdbook-spec` into errors. This is used in CI to ensure that there aren't any problems with the book content. + +```sh +SPEC_DENY_WARNINGS=1 mdbook serve --open +``` + +### `SPEC_RUST_ROOT` + +The `SPEC_RUST_ROOT` environment variable can be used to point to the directory of a checkout of . This is used by the test-linking feature so that it can find tests linked to Reference rules. If this is not set, the tests won't be linked. + +```sh +SPEC_RUST_ROOT=/path/to/rust mdbook serve --open +``` diff --git a/reference-dev-guide/src/tooling/index.md b/reference-dev-guide/src/tooling/index.md new file mode 100644 index 0000000000..be8fb539ee --- /dev/null +++ b/reference-dev-guide/src/tooling/index.md @@ -0,0 +1,10 @@ +# Reference tooling + +The Reference uses [mdBook] to convert its source files from Markdown to HTML. See [Building the Reference] for more information. Additionally, there is an mdBook extension called [`mdbook-spec`] which adds a variety of custom features used by the Reference. + +In addition to the book tooling, there is a variety of testing tools documented in the [tests chapter]. + +[`mdbook-spec`]: mdbook-spec.md +[Building the Reference]: building.md +[mdbook]: https://rust-lang.github.io/mdBook/ +[tests chapter]: ../tests.md diff --git a/reference-dev-guide/src/tooling/mdbook-spec.md b/reference-dev-guide/src/tooling/mdbook-spec.md new file mode 100644 index 0000000000..13ed32b6a2 --- /dev/null +++ b/reference-dev-guide/src/tooling/mdbook-spec.md @@ -0,0 +1,39 @@ +# mdbook-spec + +[`mdbook-spec`] is an mdBook preprocessor that adds features to the Reference. It provides: + +- Parsing and generation of [grammar diagrams]. + - [Automatic grammar production links]. + - Generation of the [grammar summary appendix]. +- [Automatic standard library links]. +- Handling of [rule names]. + - Validation of the names. + - Converting rule names to links. + - [Automatic rule link references]. + - Generation of [links to rule tests]. + - Generation of the [test summary]. +- Support for [admonitions]. + +## Environment variables + +There are a few environment variables that `mdbook-spec` uses, described in the [building chapter]: + +- [`SPEC_RELATIVE`] --- Can be set to link external books to the live site. +- [`SPEC_DENY_WARNINGS`] --- Whether warnings should be treated as errors. +- [`SPEC_RUST_ROOT`] --- The path to a checkout of the [`rust-lang/rust`] GitHub repository. This is used for test linking. + +[`mdbook-spec`]: https://github.com/rust-lang/reference/tree/master/mdbook-spec +[`rust-lang/rust`]: https://github.com/rust-lang/rust +[`SPEC_DENY_WARNINGS`]: building.md#SPEC_DENY_WARNINGS +[`SPEC_RELATIVE`]: building.md#SPEC_RELATIVE +[`SPEC_RUST_ROOT`]: building.md#SPEC_RUST_ROOT +[admonitions]: ../formatting/admonitions.md +[Automatic grammar production links]: ../grammar.md#automatic-linking +[Automatic rule link references]: ../links.md#rule-links +[Automatic standard library links]: ../links.md#standard-library-links +[Building chapter]: building.md +[grammar diagrams]: ../grammar.md +[grammar summary appendix]: https://doc.rust-lang.org/nightly/reference/grammar.html +[links to rule tests]: ../rules/test-annotations.md +[rule names]: ../rules/index.md +[test summary]: https://doc.rust-lang.org/nightly/reference/test-summary.html