Documentation post-building hook

help
1

Is it possible to alter HTML files created by cargo-doc by injecting results produced by example programs embedded in docs?

I'm working on a library that produces SVG images. Currently my docsring tests compare a produced svg string with an expected one. It would be very cool however, if the actual output of an example were shown in the page. Can I save these SVGs to files and link them somehow? Or to inject directly as text within <svg></svg> element?

2

You don't necessarily need a post-processing script; you can embed text from files in documentation, and use that carefully:

/// Example code:
///
/// ```
/// assert_eq!(generate_svg(), "
#[doc = include_str!("expected.svg")]
/// ".trim());
/// ```
///
/// This code produces this image:
///
/// <svg>
#[doc = include_str!("expected.svg")]
/// </svg>
///
/// Blah blah blah.

All #[doc = ""] and /// are concatenated together to produce the documentation text which is then parsed as Markdown.

(embed-doc-image uses this technique to embed arbitrary images by encoding them in data: URLs. You don't need any extra support because your SVGs are already embeddable text.)

2 Likes
3

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.