Cargo intraconv

cargo-intraconv 是一个简单的辅助工具，它会在合适的场合将 Rust 项目的 Markdown 链接转换为 文档内链接。

文档内链接已在 Rust 1.48.0 中稳定，有关更多信息，请参阅宣布它的博客文章。

什么是文档内链接？

以前，要编写指向您自己的包（或其他包）其他元素的链接，只有以下方式，路径取决于当前文件和目标文件

/// [`make_ascii_uppercase`]: #method.make_ascii_uppercase

/// [`Path::ancestors`]: https://doc.rust-lang.net.cn/stable/std/path/struct.Path.html#method.ancestors

/// See [the `Rotation` type](../struct.Rotation.html)

现在，可以使用 Rust 路径来编写它们，取决于目标项的路径和作用域（这意味着位于预定义中的 String 这样的项只是 [String] 之遥）。这些链接对于最初编写它们的人以及随后的读者来说都更清晰。由于文件层次结构不影响它们，因此更容易进行推理。以下是对上述示例的文档内链接版本

/// [`make_ascii_uppercase`]: u8::make_ascii_uppercase()

/// [`Path::ancestors`]: std::path::Path::ancestors()

/// See [the `Rotation` type](super::Rotation)

当链接的两端相同，甚至可以更短

/// See [`Rotation`]
///
- /// [`Rotation`]: struct.Rotation.html

- /// See [`Rotation`](struct.Rotation.html)
+ /// See [`Rotation`]

为什么是这个包？

更改所有现有链接可能是繁琐的，也可以自动化。这个包旨在帮助您尽可能痛苦地更新文档以使用文档内链接。

用法

默认情况下，由该包产生的二进制文件不会修改给定的文件，只会显示会发生变化的内容

# Call `cargo-intraconv` for a whole crate or workspace. Crate names will be
# discovered from `Cargo.toml` files.
cargo intraconv

# Call `cargo-intraconv` for specific file. No automatic crate name discovery.
cargo intraconv path/to/std/file.rs

# Specifying the root crate.
cargo intraconv path/to/core/file.rs -c core

# Applying the changes.
cargo intraconv path/to/std/file.rs -a

# Disambiguate links by prefixing them with their rustdoc group ('type@', ...).
cargo intraconv path/to/my/file.rs -d

# Do not transform favored links to intra-doc links (see below for more).
cargo intravonc path/to/my/file.rs -f

# Do not display changes, only errors.
cargo intraconv path/to/my/file.rs -q

# Give a file containing links to ignore.
#
# Note: `intraconv.toml` is read by default when present.
cargo intraconv path/to/my/file.rs -i intraconv.toml

可以为文件或目录提供多个路径。在搜索精确路径时，cargo-intraconv将使用与-c一起提供的crate名称。对于目录，它将尝试在Cargo.toml中查找crate名称，如果无法将名称转换为有效的Rust标识符，则回退到默认的-c。

注意：intraconv将接受任何文件，而不仅仅是.rs文件：例如，您可以在Rust文件中作为文档包含的Markdown文件上使用它。

首选链接

默认情况下，crate会将首选的http(s)://链接转换为内部文档链接（如来自docs.rs的链接）。要禁用此行为，请使用-（--no-favored）标志。

# Global ignores, applied everywhere.
[ignore]
# Will be deleted by the second instance of `"name"`.
"name" = [ "link 1" ] # Must be an array, a single value will not work,
                      # this allows for multiples values easily.
"name" = [ "link 2" ]
# Will only keep one instance of 'link 3'.
"other name" = [ "link 3", "link 3", "link 1" ]

# Will match exactly the lib.rs file in tracing-core.
# NOTE: this path must either be absolute OR relative to the EXACT directory
# from which `cargo-intraconv` is called.
#
# Paths must be unique whether canonicalized (for paths with more than one
# component) or not (paths with a single component, as `lib.rs` below).
["tracing-core/src/lib.rs"]
# Will match both 'downcast_ref' and '`downcast_ref`' links.
"downcast_ref" = [ "#method.downcast_ref" ] # Must be an array.

# Will match EVERY lib.rs file found.
["lib.rs"]
"downcast_ref" = [ "#method.downcast_ref" ]

[ignore]
# NEVER matches.
"`downcast_ref`" = [ "#method.downcast_ref" ]