我想记录我的箱子并在文档中包含一个表格:
//! 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 |
结果是:
我有什么选项可以在我的文档中包含长表行而不违反行长度限制?
正如弗朗西斯已经回答的那样,如果你想保持短线,你必须使用HTML。 rustdoc
使用pulldown-cmark并且不支持你想要的东西。
Tracking issue: rfc 1990 - add external doc attribute to rustc。在nightly
工具链的情况下,您可以启用external_doc
功能并包含#[doc(include = "../some/path")]
的外部Markdown文件。
有一点需要注意 - 无论在哪个模块中你将使用#[doc(include = "...")]
,路径总是相对于板条箱根(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/
等单独的文件夹中。但路径始终相对于crate根目录。
还有rdoc编译器插件(需要nightly
),它基本上做同样的事情。如何启用和使用它在项目README.md中描述。
为了稳定,我会做以下事情:
build.rs
将扫描.md
文件并将其输出为.rs
文件(相同的内容,只是在///
或//!
前面加上每一行),
把它们放在std::env::var("OUT_DIR")
文件夹中,include!(concat!(env!("OUT_DIR"), "/main-hallo-md.rs"));
。有comment_width
选项(默认为80
)和wrap_comments
选项(默认为false
)。这有助于您将评论保持在某个宽度。但我用长Markdown表格线试了一下它包裹它 - >破桌子。不要使用它。
使用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>::<></code></td>
//! <td>Ferris for president 🦀</td>
//! <td>
//! I can't think of any
//! more "funny" things
//! </td>
//! <td>oopsie</td>
//! </tr>
//! </tbody>
//! </table>