Разбейте длинные строки таблицы на несколько строк в документации - PullRequest
Новая
       16

Разбейте длинные строки таблицы на несколько строк в документации

3 голосов
/ 24 марта 2019

Я хочу документировать свой ящик и включить в документацию таблицу: 

//! 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 приводит к:

correct table

Это то, что я хочу.Однако вы могли заметить, что одна строка исходного кода очень длинная.На самом деле более 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 |

Результаты:

enter image description here

Какие варианты выполненияНужно ли включать длинные строки таблицы в мою документацию, не нарушая ограничение длины строки?

Ответы [ 2 ]

4 голосов
/ 24 марта 2019

Использовать 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>
1 голос
/ 30 марта 2019

HTML

Как уже ответил Фрэнсис, вам нужно использовать HTML, если вы хотите иметь короткие строки.rustdoc использует pulldown-cmark и поддержка того, что вы хотите, не поддерживается.

Включает внешнюю документацию

nightly & doc

Отслеживаниепроблема: rfc 1990 - добавить внешний атрибут doc к rustc .В случае набора инструментов nightly вы можете включить функцию external_doc и включить внешние файлы Markdown с помощью #[doc(include = "../some/path")].

Стоит отметить, что независимо от того, в каком модуле вы будете использовать #[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;

Вы можете хранить отдельную документацию по Markdown в папке src/, вы можете хранить ее в отдельной папке, например doc/ и т. Д. Нопуть всегда указывается относительно корня ящика.

nightly & rdoc

Существует также плагин компилятора rdoc (требуется nightly), который в основном делает то же самое.Как включить и использовать это описано в проекте README.md .

stable

Для стабильного я бы сделал следующее:

  • документация в отдельных файлах Markdown,
  • custom 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, и она обернулась -> сломанная таблица.Не используйте его.

...