docs(ref): Re-org workspace docs to be like package docs

In looking over rust-lang#10625, I remembered we've been having growing pains
with the workspace documentation.  It was originally written when there
were a lot fewer workspace features.  As more workspace features have
been added, they've been tacked on to the documentation.

This re-thinks the documentation by focusing on the schema, much like
`manifest.md` does.

src/doc/src/reference/manifest.md

@@ -516,7 +516,7 @@ external tools may wish to use them in a consistent fashion, such as referring
 to the data in `workspace.metadata` if data is missing from `package.metadata`,
 if that makes sense for the tool in question.
 
-[workspace-metadata]: workspaces.md#the-workspacemetadata-table
+[workspace-metadata]: workspaces.md#the-metadata-table
 
 #### The `default-run` field
 

src/doc/src/reference/specifying-dependencies.md

@@ -489,7 +489,7 @@ rand = { workspace = true, optional = true }
 
 [crates.io]: https://crates.io/
 [dev-dependencies]: #development-dependencies
-[workspace.dependencies]: workspaces.md#the-workspacedependencies-table
+[workspace.dependencies]: workspaces.md#the-dependencies-table
 [optional]: features.md#optional-dependencies
 [features]: features.md
 

src/doc/src/reference/unstable.md

@@ -1358,7 +1358,7 @@ for more information.
 ### Workspace Inheritance
 
 Workspace Inheritance has been stabilized in the 1.64 release.
-See [workspace.package](workspaces.md#the-workspacepackage-table), 
-[workspace.dependencies](workspaces.md#the-workspacedependencies-table), 
+See [workspace.package](workspaces.md#the-package-table), 
+[workspace.dependencies](workspaces.md#the-dependencies-table), 
 and [inheriting-a-dependency-from-a-workspace](specifying-dependencies.md#inheriting-a-dependency-from-a-workspace)
-for more information.
+for more information.

src/doc/src/reference/workspaces.md

@@ -6,36 +6,87 @@ various settings such as profiles. Packages that are part of a workspaces are
 called *workspace members*. There are two flavours of workspaces: as root
 package or as virtual manifest.
 
-### Root package
+The key points of workspaces are:
+
+* All packages share a common `Cargo.lock` file which resides in the
+  *workspace root*.
+* All packages share a common [output directory], which defaults to a
+  directory named `target` in the *workspace root*.
+* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
+  sections in `Cargo.toml` are only recognized in the *root* manifest, and
+  ignored in member crates' manifests.
+
+<a id="package-selection"></a>
+In a workspace, package-related cargo commands like [`cargo build`] can use
+the `-p` / `--package` or `--workspace` command-line flags to determine which
+packages to operate on. If neither of those flags are specified, Cargo will
+use the package in the current working directory. If the current directory is
+a virtual workspace, it will apply to all members (as if `--workspace` were
+specified on the command-line).
+
+See also [`default-members`](#the-default-members-field)
+
+The `[workspace]` table supports the following sections:
+
+* [`[workspace]`](#the-workspace-section) — Defines a workspace.
+  * [`members`](#the-members-and-exclude-fields) — Packages to include in the workspace.
+  * [`exclude`](#the-members-and-exclude-fields) — Packages to exclude from the workspace.
+  * [`default-members`](#the-default-members-field) — Packages to operate on when a specific package wasn't selected.
+  * [`metadata`](#the-metadata-table) — Extra settings for external tools.
+  * [`package`](#the-package-table) — Keys for inheriting in packages.
+  * [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies.
 
-A workspace can be created by adding a [`[workspace]`
-section](#the-workspace-section) to `Cargo.toml`. This can be added to a
-`Cargo.toml` that already defines a `[package]`, in which case the package is
+### The `[workspace]` section
+
+To create a workspace, you add the `[workspace]` table to a `Cargo.toml`:
+```toml
+[workspace]
+# ...
+```
+
+At minimum, a workspace has to have a member, either with a root package or as
+a virtual manifest.
+
+#### Root package
+
+If the [`[workspace]` section](#the-workspace-section) is added to a
+`Cargo.toml` that already defines a `[package]`, the package is
 the *root package* of the workspace. The *workspace root* is the directory
 where the workspace's `Cargo.toml` is located.
 
-### Virtual manifest
+```toml
+[workspace]
+
+[package]
+name = "hello_world" # the name of the package
+version = "0.1.0"    # the current version, obeying semver
+authors = ["Alice <a@example.com>", "Bob <b@example.com>"]
+```
+
+#### Virtual manifest
 
 Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section
 but without a [`[package]` section][package]. This is called a *virtual
 manifest*. This is typically useful when there isn't a "primary" package, or
 you want to keep all the packages organized in separate directories.
 
-### Key features
-
-The key points of workspaces are:
+```toml
+# [PROJECT_DIR]/Cargo.toml
+[workspace]
+members = ["hello_world"]
+```
 
-* All packages share a common `Cargo.lock` file which resides in the
-  *workspace root*.
-* All packages share a common [output directory], which defaults to a
-  directory named `target` in the *workspace root*.
-* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
-  sections in `Cargo.toml` are only recognized in the *root* manifest, and
-  ignored in member crates' manifests.
+```toml
+# [PROJECT_DIR]/hello_world/Cargo.toml
+[package]
+name = "hello_world" # the name of the package
+version = "0.1.0"    # the current version, obeying semver
+authors = ["Alice <a@example.com>", "Bob <b@example.com>"]
+```
 
-### The `[workspace]` section
+### The `members` and `exclude` fields 
 
-The `[workspace]` table in `Cargo.toml` defines which packages are members of
+The `[members]` and `exclude` fields define which packages are members of
 the workspace:
 
 ```toml
@@ -56,26 +107,14 @@ workspace. This can be useful if some path dependencies aren't desired to be
 in the workspace at all, or using a glob pattern and you want to remove a
 directory.
 
-An empty `[workspace]` table can be used with a `[package]` to conveniently
-create a workspace with the package and all of its path dependencies.
-
-### Workspace selection
-
 When inside a subdirectory within the workspace, Cargo will automatically
 search the parent directories for a `Cargo.toml` file with a `[workspace]`
 definition to determine which workspace to use. The [`package.workspace`]
 manifest key can be used in member crates to point at a workspace's root to
 override this automatic search. The manual setting can be useful if the member
 is not inside a subdirectory of the workspace root.
 
-### Package selection
-
-In a workspace, package-related cargo commands like [`cargo build`] can use
-the `-p` / `--package` or `--workspace` command-line flags to determine which
-packages to operate on. If neither of those flags are specified, Cargo will
-use the package in the current working directory. If the current directory is
-a virtual workspace, it will apply to all members (as if `--workspace` were
-specified on the command-line).
+### The `default-members` field
 
 The optional `default-members` key can be specified to set the members to
 operate on when in the workspace root and the package selection flags are not
@@ -89,7 +128,7 @@ default-members = ["path/to/member2", "path/to/member3/foo"]
 
 When specified, `default-members` must expand to a subset of `members`.
 
-### The `workspace.metadata` table
+### The `metadata` table
 
 The `workspace.metadata` table is ignored by Cargo and will not be warned
 about. This section can be used for tools that would like to store workspace
@@ -112,7 +151,7 @@ external tools may wish to use them in a consistent fashion, such as referring
 to the data in `workspace.metadata` if data is missing from `package.metadata`,
 if that makes sense for the tool in question.
 
-### The `workspace.package` table
+### The `package` table
 
 The `workspace.package` table is where you define keys that can be
 inherited by members of a workspace. These keys can be inherited by
@@ -157,7 +196,7 @@ description.workspace = true
 documentation.workspace = true
 ```
 
-### The `workspace.dependencies` table
+### The `dependencies` table
 
 The `workspace.dependencies` table is where you define dependencies to be
 inherited by members of a workspace.