#rustdoc #documentation #svg #diagram #figure

macro svgbobdoc

Renders ASCII diagrams in doc comments as SVG images

8 releases

new 0.3.0-alpha.3 Nov 28, 2021
0.3.0-alpha.2 Nov 23, 2021
0.3.0-alpha.1 Jul 23, 2021
0.2.3 Oct 21, 2020
0.1.0 May 29, 2019

#108 in Text processing

Download history 95/week @ 2021-08-09 208/week @ 2021-08-16 123/week @ 2021-08-23 224/week @ 2021-08-30 102/week @ 2021-09-06 542/week @ 2021-09-13 366/week @ 2021-09-20 418/week @ 2021-09-27 235/week @ 2021-10-04 174/week @ 2021-10-11 722/week @ 2021-10-18 351/week @ 2021-10-25 151/week @ 2021-11-01 125/week @ 2021-11-08 246/week @ 2021-11-15 342/week @ 2021-11-22

1,327 downloads per month
Used in 12 crates (4 directly)

MIT/Apache

33KB
706 lines

svgbobdoc

docs.rs

This crate provides a procedural macro that renders ASCII diagrams in doc comments as SVG images using svgbob.

Requires Rust version 1.54 or later or equivalent nightly builds.

Usage

Add the following line to Cargo.toml.

[dependencies]
svgbobdoc = { version = "0.2", features = ["enable"] }

transform_mdstr!

Wrap doc comments with #[doc = transform_mdstr!(...)]. Use svgbob code blocks to write ASCII diagrams.

#[doc = svgbobdoc::transform_mdstr!(
/// Some structure.
///
/// ```svgbob
///  .--------------------.
///  | Diagrams here      |
///  `--------------------'
/// ```
)]
pub struct TestStruct {}

See the example directory for a complete example.

#[transform] (deprecated)

Add the attribute #[svgbobdoc::transform] to the items to documentate. Use svgbob code blocks to write ASCII diagrams.

#[svgbobdoc::transform]
/// Some structure.
///
/// ~~~svgbob
///  .--------------------.
///  | Diagrams here      |
///  `--------------------'
/// ~~~
pub struct TestStruct {}

Limitation: This method does not work with inner attributes, meaning it's unusable for a crate-level documentation.

Tips

  • Using this macro increases the compilation time. The enable Cargo feature can be used to turn off the transformation and the compilation of most dependent packages.

  • A link reference definition ([label]: data:...) can be generated by providing a link label in a code fence header as in ~~~svgbob,[label].

License: MIT/Apache-2.0

Dependencies

~2–2.9MB
~72K SLoC

œa