Improve contributor experience for the dev-guide itself (#973)
- Fix typos in the README - Don't echo all instructions in the linkcheck.sh shellscript; this is noisy and unhelpful when developing locally. Verbose output is still enabled in CI. - Link to the index page for compiler docs, not `rustc_middle`. Note that the compiler docs are not a guide - that's us! - Remove outdated instructions about avoiding 429s. These should no longer be occurring locally now that we're using caching. - Consolidate info about `mdbook` and `mdbook-linkcheck` near each other
This commit is contained in:
Joshua Nelson
GitHub
parent
43fa1342f0
commit
a64e819af8
67
README.md
67
README.md
|
|
@ -9,8 +9,10 @@ some new part of the compiler that they haven't worked on before.
|
|||
[You can read the latest version of the guide here.](https://rustc-dev-guide.rust-lang.org/)
|
||||
|
||||
You may also find the rustdocs [for the compiler itself][rustdocs] useful.
|
||||
Note that these are not intended as a guide; it's recommended that you search
|
||||
for the docs you're looking for instead of reading them top to bottom.
|
||||
|
||||
[rustdocs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
|
||||
[rustdocs]: https://doc.rust-lang.org/nightly/nightly-rustc
|
||||
|
||||
### Contributing to the guide
|
||||
|
||||
|
|
@ -35,37 +37,10 @@ rustdocs][rustdocs].
|
|||
|
||||
### Build Instructions
|
||||
|
||||
Deactivate the CI testing link validations by commenting out the `[output.linkcheck]` field in the `book.toml` configuration file like this:
|
||||
|
||||
```toml
|
||||
[book]
|
||||
title = "Guide to Rustc Development"
|
||||
author = "Rustc developers"
|
||||
description = "A guide to developing rustc"
|
||||
|
||||
[build]
|
||||
create-missing = false
|
||||
|
||||
[output.html]
|
||||
git-repository-url = "https://github.com/rust-lang/rustc-dev-guide"
|
||||
|
||||
[output.html.fold]
|
||||
enable = true
|
||||
level = 1
|
||||
|
||||
# [output.linkcheck]
|
||||
# follow-web-links = false
|
||||
# exclude = [ "crates\\.io", "gcc\\.godbolt\\.org", "youtube\\.com", "youtu\\.be", "dl\\.acm\\.org", "cs\\.bgu\\.ac\\.il" ]
|
||||
# cache-timeout = 172800
|
||||
# warning-policy = "error"
|
||||
```
|
||||
|
||||
These validations can cause errors during local builds (see Link Validations section below). Please **do not** commit these `book.toml` file changes when you submit a pull request.
|
||||
|
||||
To build a local static HTML site, install [`mdbook`](https://github.com/rust-lang/mdBook) with:
|
||||
|
||||
```
|
||||
> cargo install mdbook
|
||||
> cargo install mdbook mdbook-linkcheck
|
||||
```
|
||||
|
||||
and execute the following command in the root of the repository:
|
||||
|
|
@ -76,6 +51,11 @@ and execute the following command in the root of the repository:
|
|||
|
||||
The build files are found in the `book` directory.
|
||||
|
||||
### Link Validations
|
||||
|
||||
We use `mdbook-linkcheck` to validate URLs included in our documentation.
|
||||
`linkcheck` will be run automatically when you build with the instructions in the section above.
|
||||
|
||||
### Pre-commit script
|
||||
|
||||
We also test that line lengths are less than 100 columns. To test this locally,
|
||||
|
|
@ -95,36 +75,11 @@ On Windows:
|
|||
New-Item -Path .git/hooks/pre-commit -ItemType HardLink -Value <absolute_path/to/check_line_lengths.sh>
|
||||
```
|
||||
|
||||
### Link Validations
|
||||
|
||||
We use `mdbook-linkcheck` to validate URLs included in our documentation. To perform link checks, uncomment the `[output.linkcheck]` field in the `book.toml` configuration file and install `mdbook-linkcheck` with:
|
||||
|
||||
```bash
|
||||
> cargo install mdbook-linkcheck
|
||||
```
|
||||
|
||||
You will need recent versions of `mdbook` and `mdbook-linkcheck` to check links.
|
||||
`linkcheck` will be run automatically when you build with the instructions in the section above.
|
||||
|
||||
**Please note**: You may receive errors like the following when link-checking is enabled on local `mdbook` builds:
|
||||
|
||||
```
|
||||
error: The server responded with 429 Too Many Requests for "https://github.com/rust-lang/rust/tree/master/src/tools/compiletest"
|
||||
|
||||
┌── tests/intro.md:6:1 ───
|
||||
│
|
||||
6 │ [`src/tools/compiletest`] directory). This section gives a brief
|
||||
│ ^ Server responded with 429 Too Many Requests
|
||||
```
|
||||
|
||||
There is not a workaround for this error at the moment. Comment out the `[output.linkcheck]` field in the `book.toml` using the build instructions above to complete a local site build without link validations.
|
||||
|
||||
|
||||
## How to fix toolstate failures
|
||||
|
||||
> **NOTE**: Currently, we do not track the rustc-dev-guide toolstate due to
|
||||
[the spurious failure](https://github.com/rust-lang/rust/pull/71731),
|
||||
but we leave this instructions for when we do it again in the future.
|
||||
[spurious failures](https://github.com/rust-lang/rust/pull/71731),
|
||||
but we leave these instructions for when we do it again in the future.
|
||||
|
||||
1. You will get a ping from the toolstate commit. e.g. https://github.com/rust-lang-nursery/rust-toolstate/commit/8ffa0e4c30ac9ba8546b7046e5c4ccc2b96ebdd4
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
set -ev
|
||||
set -e
|
||||
set -o pipefail
|
||||
|
||||
# https://docs.travis-ci.com/user/environment-variables/#default-environment-variables
|
||||
|
|
@ -8,6 +8,7 @@ if [ "$TRAVIS_EVENT_TYPE" = "cron" ] ; then # running in cron job
|
|||
FLAGS=""
|
||||
|
||||
echo "Doing full link check."
|
||||
set -x
|
||||
elif [ "$CI" = "true" ] ; then # running in PR CI build
|
||||
if [ -z "$TRAVIS_COMMIT_RANGE" ]; then
|
||||
echo "error: unexpected state: TRAVIS_COMMIT_RANGE must be non-empty in CI"
|
||||
|
|
@ -18,6 +19,7 @@ elif [ "$CI" = "true" ] ; then # running in PR CI build
|
|||
FLAGS="--no-cache -f $CHANGED_FILES"
|
||||
|
||||
echo "Checking files changed in $TRAVIS_COMMIT_RANGE: $CHANGED_FILES"
|
||||
set -x
|
||||
else # running locally
|
||||
COMMIT_RANGE=master...
|
||||
CHANGED_FILES=$(git diff --name-only $COMMIT_RANGE | tr '\n' ' ')
|
||||
|
|
|
|||
Loading…
Reference in New Issue