将长表格行在文档中分为多行

Question

我想记录我的木箱并在文档中包含一个表格：

//! Demonstrating MarkDown tables.
//!
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president  | I can't think of any more "funny" things | oopsie |
//!

使用 cargo doc 命令生成的文档如下图所示：

这就是我想要的。但是您可能已经注意到，源代码行非常长，超过了100个字符。像许多Rust项目一样，我希望保持所有行的长度不超过100个字符。因此，我尝试着对该行进行换行。

以下所有版本：

//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president  
//! I can't think of any more "funny" things | oopsie |

//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president  |
//! I can't think of any more "funny" things | oopsie |

//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president 
//! | I can't think of any more "funny" things | oopsie |

//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president  |
//! | I can't think of any more "funny" things | oopsie |

//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president  \
//! I can't think of any more "funny" things | oopsie |

结果为：

我有哪些选项可以在我的文档中包含长表格行，而不违反行长度限制？

- Lukas Kalbertodt

---

rustdoc使用pulldown-cmark，并且不支持您想要的功能。您必须像之前回答的那样使用HTML。或者a）创建单独的.md文件，准备build.rs将.md->.rs文件转换（在前面加上//!或///），然后使用include!，b）等待rustc添加外部文档属性或c）使用rdoc的nightly版本。 - zrzka

@zrzka，您想将其添加为答案吗？您可以参考有关HTML的现有答案，并提供如何使用此外部doc属性的简单示例。那将很好 :) - Lukas Kalbertodt

Answer 1

使用HTML标记语言。

//! Demonstrating HTML tables.
//!
//! <table>
//!     <thead>
//!         <tr>
//!             <th>Foo</th>
//!             <th>Bar</th>
//!             <th>Baz</th>
//!             <th>Quux</th>
//!         </tr>
//!     </thead>
//!     <tbody>
//!         <tr>
//!             <td>Hail the turbofish <code>::&lt;></code></td>
//!             <td>Ferris for president </td>
//!             <td>
//!                 I can't think of any
//!                 more "funny" things
//!             </td>
//!             <td>oopsie</td>
//!         </tr>
//!     </tbody>
//! </table>

- Francis Gagné

Answer 2

HTML

如Francis所回答的那样，如果您想保持短行，就必须使用HTML。rustdoc使用pulldown-cmark，不支持您想要的。

包含外部文档

nightly & doc

跟踪问题：rfc 1990-向rustc添加外部文档属性。在使用nightly工具链时，您可以启用external_doc功能，并使用#[doc(include = "../some/path")]包含外部Markdown文件。

需要注意的一点是-无论您在哪个模块中使用#[doc(include = "...")]，路径始终相对于crate根目录（lib.rs，main.rs，...）。

例如：

.
|____Cargo.toml
|____Cargo.lock
|____doc
| |____foo-bar-bar.md
|____src
| |____main-hallo.md
| |____foo
| | |____mod.rs
| | |____bar.rs
| |____main.rs

src/main.rs:

#![feature(external_doc)]

pub mod foo;

#[doc(include = "main-hallo.md")]
pub fn hallo() {}

fn main() {}

src/foo/bar.rs:

#[doc(include = "../doc/foo-bar-bar.md")]
pub struct Bar;

您可以在src/文件夹中保留单独的Markdown文档，也可以将其放在单独的文件夹中，例如doc/等。但路径始终相对于创建根目录。

nightly & rdoc

还有rdoc编译器插件（需要nightly），它基本上做了同样的事情。如何启用和使用它在项目README.md中有描述。

stable

对于稳定版本，我会执行以下操作：

• 将文档分别放在Markdown文件中，
• 自定义build.rs，扫描.md文件并将其输出为.rs文件（相同的内容，只需在每行前面添加///或//!），
  • 将它们放在std::env::var("OUT_DIR")文件夹中，
• 在您的源代码中包含它们，
  • 通过include!(concat!(env!("OUT_DIR"), "/main-hallo-md.rs"));。

rustfmt和nightly

有comment_width选项（默认为80）和wrap_comments选项（默认为false）。这可以帮助您保持注释的某些宽度。但是我尝试了一下长的Markdown表格行，它被换行了->破碎的表格。不要使用它。

- zrzka

---

非常好的答案！感谢您探索了各种可能的解决方案。 - Lukas Kalbertodt