70

我正在构建一个 Rust 库并想对其进行一些润色。在 rustdoc 中，我有时想链接到文档中库的其他部分，例如fns、traits 或structs。这个的官方语法是什么？

4

5 回答 5

92

从Rust 1.48开始，您现在可以依赖RFC 1946。这增加了文档内链接的概念。这允许使用Rust 路径作为链接的 URL：

  1. [Iterator](std::iter::Iterator)
  2. [Iterator][iter]，以及文档中的其他地方：[iter]: std::iter::Iterator
  3. [Iterator]，以及文档中的其他地方：[Iterator]: std::iter::Iterator

RFC 还引入了“隐含的快捷方式参考链接”。这允许省略链接引用，然后自动推断。

  1. [std::iter::Iterator]，在文档中的其他任何地方都没有 Iterator 的链接引用定义
  2. [`std::iter::Iterator`]，在文档中的任何其他地方没有迭代器的链接引用定义（与以前的样式相同，但带有反引号以将链接格式化为内联代码）

作为一个具体的例子，这个源代码：

//! Check out [ExampleStruct], especially [this
//! method](ExampleStruct::foo), but [the trait method][trait] is also
//! cool. There is also [an enum variant you can
//! use](nested::ExampleEnum::Beta).
//!
//! [trait]: ExampleTrait::bar

pub struct ExampleStruct;

impl ExampleStruct {
    pub fn foo(&self) {}
}

pub trait ExampleTrait {
    fn bar();
}

pub mod nested {
    pub enum ExampleEnum {
        Alpha,
        Beta,
    }
}

生成此文档：

示例生成的文档

具体来说，会生成以下 HTML：

<p>Check out <a href="../doc_link_example/struct.ExampleStruct.html" title="ExampleStruct">ExampleStruct</a>, especially <a href="../doc_link_example/struct.ExampleStruct.html#method.foo">this method</a>, but <a href="../doc_link_example/trait.ExampleTrait.html#tymethod.bar">the trait method</a> is also cool. There is also <a href="../doc_link_example/nested/enum.ExampleEnum.html#Beta.v">an enum variant you can use</a>.</p>
于 2018-11-27T16:39:47.847 回答
44

从 Rust 1.48 开始，Rustdoc 现在支持直接的文档内链接。

Rust 1.48 之前：

Rustdoc似乎为板条箱的组成元素生成了主要确定性的文件名。因此，如果您有一个enum名字Complex，您通常可以使用以下方法链接到它：

[Complex](enum.Complex.html)

类似地，struct被调用Point看起来像：

[Point](struct.Point.html)

这应该延续到大多数定义（fn、trait等）。

对于在不同嵌套级别引用板条箱的元素，您可以使用相对路径（其中每个模块都是其自己的文件夹）：

[Point](../model/struct.Point.html)

或使用绝对路径：

[Point](/crate_name/model/struct.Point.html)

如果构建文档cargo doc --no-deps --open（请记住，只有发布项目会发布到文档。

于 2016-08-17T09:56:02.657 回答
8

如果想要链接结构的某些特定部分，例如，foo在同一结构中命名的方法（使用stable rust，而不是nightly）

[foo](#method.foo)

或者如果它在另一个结构中

[foo](struct.OtherStruct.html#method.foo)
于 2018-11-27T14:01:16.117 回答
1

在 Rust 1.49 nightly中它可以工作（1.48 stable 尚未发布）：

  • [ super::structs::WebApiResponse]
  • [ mycrate::structs::WebApiResponse]

等等

在这里阅读

于 2020-10-24T08:06:26.507 回答
0

由于文档是用 Markdown 编写的，因此只需对超链接使用 Markdown 语法即可；IE

[anchor text](URL)

另外，看看这个：https ://doc.rust-lang.org/book/documentation.html

于 2015-07-29T13:38:15.103 回答