Crate svgbobdoc[−][src]
Expand description
svgbobdoc
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 dependencies’ compilation.
Other forms of macros
The macro is currently implemented as an attribute macro, which has restrictions, e.g., they cannot be attached to fields and non-inline modules. Other forms of macros were considered, but they were unusable for this purpose for the following reasons:
-
Function-like macros producing a part of an attribute (
#[svgbobdoc::doc!("...")]
): Macros in this position aren’t expanded, causing a parsing error. -
Function-like macros expanding to an attribute (
svgbobdoc::doc!("...")
): Procedural macros cannot expand to an attribute.
Therefore, despite its downsides, an attribute macro is the only working solution known at the moment.
License: MIT/Apache-2.0
Macros
Render ASCII-diagram code blocks in a Markdown-formatted string literal or
zero or more #[doc = ...]
attributes as SVG images.
Attribute Macros
Render ASCII-diagram code blocks in doc comments as SVG images.