问题标签 [rustdoc]

可以使用以下命令为 crate 设置favicon和rustdoc的徽标：

• #![doc(html_favicon_url = "<url_to>/favicon.ico")]
• #![doc(html_logo_url = "<url_to>/logo.png")]

如此处所述。

但是，我不想公开上传我的徽标，因此希望自动将这些文件包含在/target/doc其中并从那里引用它们。

目前，我已将各自的数据 url（base64 编码）放入这些字段中，它工作正常，但它极大地膨胀了设置这些属性的源文件。

我知道我可以在target/doc使用脚本生成文档后将图像复制到其中，然后使用相对 url 引用它们，但我想避免这种情况，这样我仍然可以使用cargo doc.

编辑

评论中关于设置using--output标志的建议也没有奏效，因为它导致. 除此之外，它不适合我，因为（至少据我所知）我只能在那里给出绝对路径，而我需要使用图像的相对路径的解决方案，因为我将这些图像存储在cargo 根目录的子目录，以便使用 git 等轻松转移到另一个系统。rustdocrustdocflags.cargo/config.tomlerror: Option 'output' given more than once

我使用 stable 运行代码并使用 nightly 记录它，主要是因为自动链接。

我试图#![doc = include_str!("doc.md")]在代码中包含一个很长的内部文档，但只有在每晚使用时才使用它，因为它不稳定。执行此操作的标准方法似乎是使用显式功能。

nightly我在 Cargo.toml 上声明了一个特性，并尝试了：

可以按预期使用cargo +nightly doc --features nightly，但稳定版不支持：

我怀疑cfg_attr即使不使用它们也必须解析所有参数，因此其中的宏语法#[]使事情变得更加复杂。

我怎样才能正确地做到这一点？

假设我在 VSCode 项目中有以下目录结构：

现在我想编译所有main.rs文件的注释。在这种情况下，那就是MY_EXAMPLES/Example_1/src/main.rsand MY_EXAMPLES/Example_2/src/main.rs。请注意，我希望此解决方案可扩展，因此如果我有 10 或 20 个 Example_X 文件夹，我可以自动编译注释。

MY_EXAMPLES/Example_1/src/main.rs

MY_EXAMPLES/Example_2/src/main.rs

跑步：

应该创建一个 README.md 文件，如下所示：

示例_1

我想添加到我的 README.md 的示例 1 的注释

示例_2

我想添加到我的 README.md 中的示例 2 注释

所以我们的 README.md 内容的通用模板类似于：

rustdoc 是否有任何类型的模板系统，类似于 JSDoc 等？我也看到了这个类似的问题，目前没有答案。

我想在 rust doc 注释中显示一个矩阵（数学实体）。我尝试使用这个：

虽然它在代码中看起来可以接受，但生成的注释似乎删除了每个矩阵元素之间的额外空格。它看起来像这样：

正确格式化此矩阵的最佳方法是什么？或者这是我能得到的最好的？

我的 IDE 是 VS Code，只安装了扩展 rust-analyser。

更新：

这似乎不是 IDE 问题，因为使用生成的文档cargo doc --open显示了类似的未格式化矩阵：

当我运行时cargo doc，它似乎没有为我的项目中的库生成文档。我正在使用最新版本的 Rust，正如这篇文章所回答的那样：如何在通过 Cargo 生成文档时包含私有模块？

这是我的结构：

main.rs仅包含要启动的“主要”功能：

lib.rs包含实际逻辑：

然后my_service.rs包含更多逻辑：

mod.rsinsidemy_service文件夹只是作为一个入口点：

此代码编译并成功执行，但我不确定为什么文档没有正确生成。

这是我运行时生成的文档的屏幕截图cargo doc --open：

我在任何地方都找不到MyService文档...（单击“结构”链接只会跳转到主页上的锚点）

我正在查看此页面上的官方 Diesel 文档：https ://docs.diesel.rs/diesel/expression_methods/trait.PgArrayExpressionMethods.html#example 。该示例使用变量tags，但我看不到它的定义位置。我应该如何理解这个代码片段？

tags变量从何而来？

在我的另一个问题中，我询问了如何仅公开公开Foo<u32>私有泛型类型 ( ) 的具体变体 ( Foo<T>)。建议的解决方案如下：

这有效，因为公共 API 只包含FooBar，但不包含Foo。但是，从文档的角度来看，它是缺乏的。这是cargo docfor的输出FooBar：

如你看到的，

• 私有类型Foo出现在文档中，但它不是链接，Foo也没有单独的
• 的私人文档和 的私人文档Foo均未Foo.x显示

因此，该文档并不是真正有用的。显然，我可以在 的文档中添加更多信息FooBar，但这仍然不会使 的文档FooBar看起来像常规的struct.

使用这种方法，文档FooBar显然不如这样的“等效”定义FooBar：

我将“等价物”放在引号中，因为我确实假设从编译器的角度来看（显然是 的cargo doc），这两个定义FooBar是完全不同的。我的问题是我的文档的读者不必关心这种差异。

在这种情况下，有没有办法实现“自然”文档？

如果有必要，我很乐意使用完全不同的方法来隐藏通用Foo定义。

我正在使用Cargo 功能对库中的某些内容进行条件编译。

当我记录库时，我注意到 Cargo 功能没有出现在生成的文档中。当我使用 生成文档时cargo doc --all-features，我希望看到某种标签告诉用户 struct X 仅在启用功能 Y 时可用。

手动在每个项目上写这些信息似乎很容易出错，那么有没有办法自动生成这样的东西呢？

Rustdoc 有一个rustdoc::broken_intra_doc_links用于检查文档状态的 lint。我想通过命令行标志将此 lint 变为错误。大多数 rust lints 可以通过配置，-D flags但我不知道如何为 rustdoc 配置它，即使在命令行上显式调用它也是如此。我试过例如

cargo rustdoc -p mycrate -- -D "rustdoc::broken_intra_doc_links"

但这只是给了我错误error[E0602]: unknown lint: 'broken_intra_doc_links'

我知道我可以#![deny(rustdoc::broken_intra_doc_links)]在代码中标记这个，我不想这样做。

根据doc.rust-lang.org

• cargo rustdoc

使用指定的自定义标志构建 [s] 包的文档

• cargo doc

构建一个包的文档

两者有什么区别？据我了解cargo rustdoc，就像cargo doc，但它允许更多的 lints - 例如：

这个对吗？奇怪的是，cargo rustdoc在某些情况下也会失败cargo doc。例如

此外，cargo doc不支持添加-D选项，而支持cargo rustdoc。