Skip to content

Commit

Permalink
Auto merge of #12339 - ehuss:heading-attributes, r=weihanglo
Browse files Browse the repository at this point in the history 
docs: Use heading attributes to control the fragment.

mdBook recently gained the ability to use [heading attributes](https://rust-lang.github.io/mdBook/format/markdown.html#heading-attributes) which allows you to define the HTML id (and thus URL fragment) for a section. This is an improvement over using manual `id` tags since mdBook can now know which ID matches the section, and will automatically set up links and such.

Some of these pages were using `id` tags to handle backwards-compat for old URLs. For those, I switched them to use redirects instead.

One downside is that the links won't work in GitHub render previews. Overall I think the benefits are worth it, though.
  • Loading branch information
@bors
bors committed Jul 12, 2023
2 parents a94d1d0 + a181267 commit ee100cc
Show file tree
Hide file tree
Showing 5 changed files with 79 additions and 118 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/main.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ jobs:
- name: Install mdbook
run: |
mkdir mdbook
curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.27/mdbook-v0.4.27-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.31/mdbook-v0.4.31-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
echo `pwd`/mdbook >> $GITHUB_PATH
- run: cd src/doc && mdbook build --dest-dir ../../target/doc
- name: Run linkchecker.sh
Expand Down
47 changes: 16 additions & 31 deletions src/doc/src/reference/build-scripts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ The sections below describe how build scripts work, and the [examples
chapter](build-script-examples.md) shows a variety of examples on how to write
scripts.

> Note: The [`package.build` manifest key](manifest.md#package-build) can be
> Note: The [`package.build` manifest key](manifest.md#the-build-field) can be
> used to change the name of the build script, or disable it entirely.
### Life Cycle of a Build Script
Expand Down Expand Up @@ -132,8 +132,7 @@ one detailed below.
scripts.


<a id="rustc-link-arg"></a>
#### `cargo:rustc-link-arg=FLAG`
#### `cargo:rustc-link-arg=FLAG` {#rustc-link-arg}

The `rustc-link-arg` instruction tells Cargo to pass the [`-C link-arg=FLAG`
option][link-arg] to the compiler, but only when building supported targets
Expand All @@ -143,26 +142,23 @@ linker script.

[link-arg]: ../../rustc/codegen-options/index.md#link-arg

<a id="rustc-link-arg-bin"></a>
#### `cargo:rustc-link-arg-bin=BIN=FLAG`
#### `cargo:rustc-link-arg-bin=BIN=FLAG` {#rustc-link-arg-bin}

The `rustc-link-arg-bin` instruction tells Cargo to pass the [`-C
link-arg=FLAG` option][link-arg] to the compiler, but only when building
the binary target with name `BIN`. Its usage is highly platform specific. It is useful
to set a linker script or other linker options.


<a id="rustc-link-arg-bins"></a>
#### `cargo:rustc-link-arg-bins=FLAG`
#### `cargo:rustc-link-arg-bins=FLAG` {#rustc-link-arg-bins}

The `rustc-link-arg-bins` instruction tells Cargo to pass the [`-C
link-arg=FLAG` option][link-arg] to the compiler, but only when building a
binary target. Its usage is highly platform specific. It is useful
to set a linker script or other linker options.


<a id="rustc-link-lib"></a>
#### `cargo:rustc-link-lib=LIB`
#### `cargo:rustc-link-lib=LIB` {#rustc-link-lib}

The `rustc-link-lib` instruction tells Cargo to link the given library using
the compiler's [`-l` flag][option-link]. This is typically used to link a
Expand All @@ -187,30 +183,26 @@ The optional `KIND` may be one of `dylib`, `static`, or `framework`. See the
[FFI]: ../../nomicon/ffi.md


<a id="rustc-link-arg-tests"></a>
#### `cargo:rustc-link-arg-tests=FLAG`
#### `cargo:rustc-link-arg-tests=FLAG` {#rustc-link-arg-tests}

The `rustc-link-arg-tests` instruction tells Cargo to pass the [`-C
link-arg=FLAG` option][link-arg] to the compiler, but only when building a
tests target.


<a id="rustc-link-arg-examples"></a>
#### `cargo:rustc-link-arg-examples=FLAG`
#### `cargo:rustc-link-arg-examples=FLAG` {#rustc-link-arg-examples}

The `rustc-link-arg-examples` instruction tells Cargo to pass the [`-C
link-arg=FLAG` option][link-arg] to the compiler, but only when building an examples
target.

<a id="rustc-link-arg-benches"></a>
#### `cargo:rustc-link-arg-benches=FLAG`
#### `cargo:rustc-link-arg-benches=FLAG` {#rustc-link-arg-benches}

The `rustc-link-arg-benches` instruction tells Cargo to pass the [`-C
link-arg=FLAG` option][link-arg] to the compiler, but only when building a benchmark
target.

<a id="rustc-link-search"></a>
#### `cargo:rustc-link-search=[KIND=]PATH`
#### `cargo:rustc-link-search=[KIND=]PATH` {#rustc-link-search}

The `rustc-link-search` instruction tells Cargo to pass the [`-L`
flag][option-search] to the compiler to add a directory to the library search
Expand All @@ -228,16 +220,14 @@ is fine).

[option-search]: ../../rustc/command-line-arguments.md#option-l-search-path

<a id="rustc-flags"></a>
#### `cargo:rustc-flags=FLAGS`
#### `cargo:rustc-flags=FLAGS` {#rustc-flags}

The `rustc-flags` instruction tells Cargo to pass the given space-separated
flags to the compiler. This only allows the `-l` and `-L` flags, and is
equivalent to using [`rustc-link-lib`](#rustc-link-lib) and
[`rustc-link-search`](#rustc-link-search).

<a id="rustc-cfg"></a>
#### `cargo:rustc-cfg=KEY[="VALUE"]`
#### `cargo:rustc-cfg=KEY[="VALUE"]` {#rustc-cfg}

The `rustc-cfg` instruction tells Cargo to pass the given value to the
[`--cfg` flag][option-cfg] to the compiler. This may be used for compile-time
Expand All @@ -258,8 +248,7 @@ identifier, the value should be a string.
[conditional compilation]: ../../reference/conditional-compilation.md
[option-cfg]: ../../rustc/command-line-arguments.md#option-cfg

<a id="rustc-env"></a>
#### `cargo:rustc-env=VAR=VALUE`
#### `cargo:rustc-env=VAR=VALUE` {#rustc-env}

The `rustc-env` instruction tells Cargo to set the given environment variable
when compiling the package. The value can be then retrieved by the [`env!`
Expand All @@ -279,17 +268,15 @@ Cargo][env-cargo].
[env-macro]: ../../std/macro.env.html
[env-cargo]: environment-variables.md#environment-variables-cargo-sets-for-crates

<a id="rustc-cdylib-link-arg"></a>
#### `cargo:rustc-cdylib-link-arg=FLAG`
#### `cargo:rustc-cdylib-link-arg=FLAG` {#rustc-cdylib-link-arg}

The `rustc-cdylib-link-arg` instruction tells Cargo to pass the [`-C
link-arg=FLAG` option][link-arg] to the compiler, but only when building a
`cdylib` library target. Its usage is highly platform specific. It is useful
to set the shared library version or the runtime-path.


<a id="cargo-warning"></a>
#### `cargo:warning=MESSAGE`
#### `cargo:warning=MESSAGE` {#cargo-warning}

The `warning` instruction tells Cargo to display a warning after the build
script has finished running. Warnings are only shown for `path` dependencies
Expand Down Expand Up @@ -334,8 +321,7 @@ FAQ](../faq.md#why-is-cargo-rebuilding-my-code).

[`exclude` and `include` fields]: manifest.md#the-exclude-and-include-fields

<a id="rerun-if-changed"></a>
#### `cargo:rerun-if-changed=PATH`
#### `cargo:rerun-if-changed=PATH` {#rerun-if-changed}

The `rerun-if-changed` instruction tells Cargo to re-run the build script if
the file at the given path has changed. Currently, Cargo only uses the
Expand All @@ -354,8 +340,7 @@ automatically handles whether or not the script itself needs to be recompiled,
and of course the script will be re-run after it has been recompiled.
Otherwise, specifying `build.rs` is redundant and unnecessary.

<a id="rerun-if-env-changed"></a>
#### `cargo:rerun-if-env-changed=NAME`
#### `cargo:rerun-if-env-changed=NAME` {#rerun-if-env-changed}

The `rerun-if-env-changed` instruction tells Cargo to re-run the build script
if the value of an environment variable of the given name has changed.
Expand Down
22 changes: 11 additions & 11 deletions src/doc/src/reference/manifest.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,6 @@ Every manifest file consists of the following sections:
* [`[profile]`](profiles.md) --- Compiler settings and optimizations.
* [`[workspace]`](workspaces.md) --- The workspace definition.

<a id="package-metadata"></a>
### The `[package]` section

The first section in a `Cargo.toml` is `[package]`.
Expand Down Expand Up @@ -112,7 +111,6 @@ breaking change.
[Resolver]: resolver.md
[SemVer compatibility]: semver.md

<a id="the-authors-field-optional"></a>
#### The `authors` field

The optional `authors` field lists in an array the people or organizations that are considered
Expand All @@ -135,7 +133,6 @@ user interface.
> field cannot be changed or removed in already-published versions of a
> package.
<a id="the-edition-field-optional"></a>
#### The `edition` field

The `edition` key is an optional key that affects which [Rust Edition] your package
Expand Down Expand Up @@ -198,7 +195,6 @@ description = "A short description of my package"

> **Note**: [crates.io] requires the `description` to be set.
<a id="the-documentation-field-optional"></a>
#### The `documentation` field

The `documentation` field specifies a URL to a website hosting the crate's
Expand Down Expand Up @@ -326,7 +322,6 @@ categories = ["command-line-utilities", "development-tools::cargo-plugins"]
> match one of the strings available at <https://crates.io/category_slugs>, and
> must match exactly.
<a id="the-workspace--field-optional"></a>
#### The `workspace` field

The `workspace` field can be used to configure the workspace that this package
Expand All @@ -347,8 +342,6 @@ table defined. That is, a crate cannot both be a root crate in a workspace

For more information, see the [workspaces chapter](workspaces.md).

<a id="package-build"></a>
<a id="the-build-field-optional"></a>
#### The `build` field

The `build` field specifies a file in the package root which is a [build
Expand All @@ -368,7 +361,6 @@ The default is `"build.rs"`, which loads the script from a file named
specify a path to a different file or `build = false` to disable automatic
detection of the build script.

<a id="the-links-field-optional"></a>
#### The `links` field

The `links` field specifies the name of a native library that is being linked
Expand All @@ -386,7 +378,6 @@ on Linux) may specify:
links = "git2"
```

<a id="the-exclude-and-include-fields-optional"></a>
#### The `exclude` and `include` fields

The `exclude` and `include` fields can be used to explicitly specify which
Expand Down Expand Up @@ -476,7 +467,6 @@ if any of those files change.

[gitignore]: https://git-scm.com/docs/gitignore

<a id="the-publish--field-optional"></a>
#### The `publish` field

The `publish` field can be used to prevent a package from being published to a
Expand All @@ -501,7 +491,6 @@ publish = ["some-registry-name"]
If publish array contains a single registry, `cargo publish` command will use
it when `--registry` flag is not specified.

<a id="the-metadata-table-optional"></a>
#### The `metadata` table

Cargo by default will warn about unused keys in `Cargo.toml` to assist in
Expand Down Expand Up @@ -624,6 +613,17 @@ more detail.
"#the-patch-section": "overriding-dependencies.html#the-patch-section",
"#using-patch-with-multiple-versions": "overriding-dependencies.html#using-patch-with-multiple-versions",
"#the-replace-section": "overriding-dependencies.html#the-replace-section",
"#package-metadata": "manifest.html#the-package-section",
"#the-authors-field-optional": "manifest.html#the-authors-field",
"#the-edition-field-optional": "manifest.html#the-edition-field",
"#the-documentation-field-optional": "manifest.html#the-documentation-field",
"#the-workspace--field-optional": "manifest.html#the-workspace-field",
"#package-build": "manifest.html#the-build-field",
"#the-build-field-optional": "manifest.html#the-build-field",
"#the-links-field-optional": "manifest.html#the-links-field",
"#the-exclude-and-include-fields-optional": "manifest.html#the-exclude-and-include-fields",
"#the-publish--field-optional": "manifest.html#the-publish-field",
"#the-metadata-table-optional": "manifest.html#the-metadata-table",
};
var target = fragments[window.location.hash];
if (target) {
Expand Down
Loading

0 comments on commit ee100cc

Please sign in to comment.