Auto merge of #12595 - weihanglo:doc-headings, r=epage

doc: adjust all doc headings one level up

Author: bors

src/doc/src/appendix/glossary.md

@@ -1,25 +1,25 @@
 # Glossary
 
-### Artifact
+## Artifact
 
 An *artifact* is the file or set of files created as a result of the
 compilation process. This includes linkable libraries, executable binaries,
 and generated documentation.
 
-### Cargo
+## Cargo
 
 *Cargo* is the Rust [*package manager*](#package-manager), and the primary
 topic of this book.
 
-### Cargo.lock
+## Cargo.lock
 
 See [*lock file*](#lock-file).
 
-### Cargo.toml
+## Cargo.toml
 
 See [*manifest*](#manifest).
 
-### Crate
+## Crate
 
 A Rust *crate* is either a library or an executable program, referred to as
 either a *library crate* or a *binary crate*, respectively.
@@ -32,14 +32,14 @@ compressed package fetched from a [registry](#registry).
 
 The source code for a given crate may be subdivided into [*modules*](#module).
 
-### Edition
+## Edition
 
 A *Rust edition* is a developmental landmark of the Rust language. The
 [edition of a package][edition-field] is specified in the `Cargo.toml`
 [manifest](#manifest), and individual targets can specify which edition they
 use. See the [Edition Guide] for more information.
 
-### Feature
+## Feature
 
 The meaning of *feature* depends on the context:
 
@@ -58,32 +58,32 @@ The meaning of *feature* depends on the context:
 - CPU targets have [*target features*][target-feature] which specify
   capabilities of a CPU.
 
-### Index
+## Index
 
 The *index* is the searchable list of [*crates*](#crate) in a
 [*registry*](#registry).
 
-### Lock file
+## Lock file
 
 The `Cargo.lock` *lock file* is a file that captures the exact version of
 every dependency used in a [*workspace*](#workspace) or
 [*package*](#package). It is automatically generated by Cargo. See
 [Cargo.toml vs Cargo.lock].
 
-### Manifest
+## Manifest
 
 A [*manifest*][manifest] is a description of a [package](#package) or a
 [workspace](#workspace) in a file named `Cargo.toml`.
 
 A [*virtual manifest*][virtual] is a `Cargo.toml` file that only describes a
 workspace, and does not include a package.
 
-### Member
+## Member
 
 A *member* is a [*package*](#package) that belongs to a
 [*workspace*](#workspace).
 
-### Module
+## Module
 
 Rust's module system is used to organize code into logical units called
 *modules*, which provide isolated namespaces within the code.
@@ -98,7 +98,7 @@ A [`Cargo.toml`](#manifest) file is primarily concerned with the
 which they depend. Nevertheless, you will see the term "module" often when
 working with Rust, so you should understand its relationship to a given crate.
 
-### Package
+## Package
 
 A *package* is a collection of source files and a `Cargo.toml`
 [*manifest*](#manifest) file which describes the package. A package has a name
@@ -123,7 +123,7 @@ Larger projects may involve multiple packages, in which case Cargo
 [*workspaces*](#workspace) can be used to manage common dependencies and other
 related metadata between the packages.
 
-### Package manager
+## Package manager
 
 Broadly speaking, a *package manager* is a program (or collection of related
 programs) in a software ecosystem that automates the process of obtaining,
@@ -139,15 +139,15 @@ downloads your Rust [package](#package)’s dependencies
 packages, makes distributable packages, and (optionally) uploads them to
 [crates.io][], the Rust community’s [*package registry*](#registry).
 
-### Package registry
+## Package registry
 
 See [*registry*](#registry).
 
-### Project
+## Project
 
 Another name for a [package](#package).
 
-### Registry
+## Registry
 
 A *registry* is a service that contains a collection of downloadable
 [*crates*](#crate) that can be installed or used as dependencies for a
@@ -156,7 +156,7 @@ A *registry* is a service that contains a collection of downloadable
 contains a list of all crates, and tells Cargo how to download the crates that
 are needed.
 
-### Source
+## Source
 
 A *source* is a provider that contains [*crates*](#crate) that may be included
 as dependencies for a [*package*](#package). There are several kinds of
@@ -174,11 +174,11 @@ sources:
 
 See [Source Replacement] for more information.
 
-### Spec
+## Spec
 
 See [package ID specification](#package).
 
-### Target
+## Target
 
 The meaning of the term *target* depends on the context:
 
@@ -216,7 +216,7 @@ The meaning of the term *target* depends on the context:
   Some parameters may be omitted. Run `rustc --print target-list` for a list of
   supported targets.
 
-### Test Targets
+## Test Targets
 
 Cargo *test targets* generate binaries which help verify proper operation and
 correctness of code. There are two types of test artifacts:
@@ -232,7 +232,7 @@ correctness of code. There are two types of test artifacts:
   `Cargo.toml` [*manifest*](#manifest). It is intended to only test the public
   API of a library, or execute a binary to verify its operation.
 
-### Workspace
+## Workspace
 
 A [*workspace*][workspace] is a collection of one or more
 [*packages*](#package) that share common dependency resolution (with a shared

src/doc/src/faq.md

@@ -1,6 +1,6 @@
-## Frequently Asked Questions
+# Frequently Asked Questions
 
-### Is the plan to use GitHub as a package repository?
+## Is the plan to use GitHub as a package repository?
 
 No. The plan for Cargo is to use [crates.io], like npm or Rubygems do with
 [npmjs.com][1] and [rubygems.org][3].
@@ -9,7 +9,7 @@ We plan to support git repositories as a source of packages forever,
 because they can be used for early development and temporary patches,
 even when people use the registry as the primary source of packages.
 
-### Why build crates.io rather than use GitHub as a registry?
+## Why build crates.io rather than use GitHub as a registry?
 
 We think that it’s very important to support multiple ways to download
 packages, including downloading from GitHub and copying packages into
@@ -43,7 +43,7 @@ languages include:
   down fast. Also remember that not everybody has a high-speed,
   low-latency Internet connection.
 
-### Will Cargo work with C code (or other languages)?
+## Will Cargo work with C code (or other languages)?
 
 Yes!
 
@@ -56,7 +56,7 @@ Our solution: Cargo allows a package to [specify a script](reference/build-scrip
 implement platform-specific configuration and refactor out common build
 functionality among packages.
 
-### Can Cargo be used inside of `make` (or `ninja`, or ...)
+## Can Cargo be used inside of `make` (or `ninja`, or ...)
 
 Indeed. While we intend Cargo to be useful as a standalone way to
 compile Rust packages at the top-level, we know that some people will
@@ -68,7 +68,7 @@ have some work to do on those fronts, but using Cargo in the context of
 conventional scripts is something we designed for from the beginning and
 will continue to prioritize.
 
-### Does Cargo handle multi-platform packages or cross-compilation?
+## Does Cargo handle multi-platform packages or cross-compilation?
 
 Rust itself provides facilities for configuring sections of code based
 on the platform. Cargo also supports [platform-specific
@@ -80,7 +80,7 @@ configuration in `Cargo.toml` in the future.
 In the longer-term, we’re looking at ways to conveniently cross-compile
 packages using Cargo.
 
-### Does Cargo support environments, like `production` or `test`?
+## Does Cargo support environments, like `production` or `test`?
 
 We support environments through the use of [profiles] to support:
 
@@ -92,7 +92,7 @@ We support environments through the use of [profiles] to support:
 * environment-specific `#[cfg]`
 * a `cargo test` command
 
-### Does Cargo work on Windows?
+## Does Cargo work on Windows?
 
 Yes!
 
@@ -102,7 +102,7 @@ issue][cargo-issues].
 
 [cargo-issues]: https://github.com/rust-lang/cargo/issues
 
-### Why have `Cargo.lock` in version control?
+## Why have `Cargo.lock` in version control?
 
 While [`cargo new`] defaults to tracking `Cargo.lock` in version control,
 whether you do is dependent on the needs of your package.
@@ -144,7 +144,7 @@ see [Verifying Latest Dependencies](guide/continuous-integration.md#verifying-la
 [`cargo add`]: commands/cargo-add.md
 [`cargo install`]: commands/cargo-install.md
 
-### Can libraries use `*` as a version for their dependencies?
+## Can libraries use `*` as a version for their dependencies?
 
 **As of January 22nd, 2016, [crates.io] rejects all packages (not just libraries)
 with wildcard dependency constraints.**
@@ -154,7 +154,7 @@ of `*` says “This will work with every version ever”, which is never going
 to be true. Libraries should always specify the range that they do work with,
 even if it’s something as general as “every 1.x.y version”.
 
-### Why `Cargo.toml`?
+## Why `Cargo.toml`?
 
 As one of the most frequent interactions with Cargo, the question of why the
 configuration file is named `Cargo.toml` arises from time to time. The leading
@@ -172,7 +172,7 @@ but others were accidentally forgotten.
 
 [crates.io]: https://crates.io/
 
-### How can Cargo work offline?
+## How can Cargo work offline?
 
 Cargo is often used in situations with limited or no network access such as
 airplanes, CI environments, or embedded in large production deployments. Users
@@ -216,7 +216,7 @@ replacement][replace].
 [`cargo fetch`]: commands/cargo-fetch.md
 [offline config]: reference/config.md#netoffline
 
-### Why is Cargo rebuilding my code?
+## Why is Cargo rebuilding my code?
 
 Cargo is responsible for incrementally compiling crates in your project. This
 means that if you type `cargo build` twice the second one shouldn't rebuild your
@@ -274,7 +274,7 @@ If after trying to debug your issue, however, you're still running into problems
 then feel free to [open an
 issue](https://github.com/rust-lang/cargo/issues/new)!
 
-### What does "version conflict" mean and how to resolve it?
+## What does "version conflict" mean and how to resolve it?
 
 > failed to select a version for `x` which could resolve this conflict
 

src/doc/src/getting-started/first-steps.md

@@ -1,4 +1,4 @@
-## First Steps with Cargo
+# First Steps with Cargo
 
 This section provides a quick sense for the `cargo` command line tool. We
 demonstrate its ability to generate a new [***package***][def-package] for us,
@@ -73,7 +73,7 @@ $ cargo run
 Hello, world!
 ```
 
-### Going further
+## Going further
 
 For more details on using Cargo, check out the [Cargo Guide](../guide/index.md)
 

src/doc/src/getting-started/index.md

@@ -1,4 +1,4 @@
-## Getting Started
+# Getting Started
 
 To get started with Cargo, install Cargo (and Rust) and set up your first
 [*crate*][def-crate].

src/doc/src/getting-started/installation.md

@@ -1,6 +1,6 @@
-## Installation
+# Installation
 
-### Install Rust and Cargo
+## Install Rust and Cargo
 
 The easiest way to get Cargo is to install the current stable release of [Rust]
 by using [rustup]. Installing Rust using `rustup` will also install `cargo`.
@@ -27,7 +27,7 @@ channels for Rust and Cargo.
 For other installation options and information, visit the
 [install][install-rust] page of the Rust website.
 
-### Build and Install Cargo from Source
+## Build and Install Cargo from Source
 
 Alternatively, you can [build Cargo from source][compiling-from-source].
 

src/doc/src/guide/build-cache.md

@@ -1,4 +1,4 @@
-## Build cache
+# Build cache
 
 Cargo stores the output of a build into the "target" directory. By default,
 this is the directory named `target` in the root of your
@@ -63,7 +63,7 @@ Directory | Description
 <code style="white-space: nowrap">target/debug/incremental/</code> | `rustc` [incremental output], a cache used to speed up subsequent builds.
 <code style="white-space: nowrap">target/debug/build/</code> | Output from [build scripts].
 
-### Dep-info files
+## Dep-info files
 
 Next to each compiled artifact is a file called a "dep info" file with a `.d`
 suffix. This file is a Makefile-like syntax that indicates all of the file
@@ -77,7 +77,7 @@ re-executed. The paths in the file are absolute by default. See the
 /path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs
 ```
 
-### Shared cache
+## Shared cache
 
 A third party tool, [sccache], can be used to share built dependencies across
 different workspaces.

src/doc/src/guide/cargo-home.md

@@ -1,4 +1,4 @@
-## Cargo Home
+# Cargo Home
 
 The "Cargo home" functions as a download and source cache.
 When building a [crate][def-crate], Cargo stores downloaded build dependencies in the Cargo home.

src/doc/src/guide/cargo-toml-vs-cargo-lock.md

@@ -1,4 +1,4 @@
-## Cargo.toml vs Cargo.lock
+# Cargo.toml vs Cargo.lock
 
 `Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk
 about them, here’s a summary:

src/doc/src/guide/continuous-integration.md

@@ -1,10 +1,10 @@
-## Continuous Integration
+# Continuous Integration
 
-### Getting Started
+## Getting Started
 
 A basic CI will build and test your projects:
 
-### GitHub Actions
+## GitHub Actions
 
 To test your package on GitHub Actions, here is a sample `.github/workflows/ci.yml` file:
 
@@ -38,7 +38,7 @@ jobs:
 
 This will test all three release channels (note a failure in any toolchain version will fail the entire job). You can also click `"Actions" > "new workflow"` in the GitHub UI and select Rust to add the [default configuration](https://github.com/actions/starter-workflows/blob/main/ci/rust.yml) to your repo. See [GitHub Actions documentation](https://docs.github.com/en/actions) for more information.
 
-### GitLab CI
+## GitLab CI
 
 To test your package on GitLab CI, here is a sample `.gitlab-ci.yml` file:
 
@@ -67,7 +67,7 @@ breakage in nightly will not fail your overall build. Please see the
 [GitLab CI documentation](https://docs.gitlab.com/ce/ci/yaml/index.html) for more
 information.
 
-### builds.sr.ht
+## builds.sr.ht
 
 To test your package on sr.ht, here is a sample `.build.yml` file.
 Be sure to change `<your repo>` and `<your project>` to the repo to clone and
@@ -105,7 +105,7 @@ channel, but any breakage in nightly will not fail your overall build. Please
 see the [builds.sr.ht documentation](https://man.sr.ht/builds.sr.ht/) for more
 information.
 
-### Verifying Latest Dependencies
+## Verifying Latest Dependencies
 
 When [specifying dependencies](../reference/specifying-dependencies.md) in
 `Cargo.toml`, they generally match a range of versions.