embed_doc_image_showcase/
lib.rs

1//! Showcase for `embed-doc-image`.
2//!
3// Important: note the blank line of documentation on each side of the image lookup table.
4// The "image lookup table" can be placed anywhere, but we place it here together with the
5// warning if the `doc-images` feature is not enabled.
6#![cfg_attr(feature = "doc-images",
7cfg_attr(all(),
8doc = ::embed_doc_image::embed_image!("ferris", "images/rustacean-orig-noshadow-tiny.png"),
9doc = ::embed_doc_image::embed_image!("ferris-gesture", "images/rustacean-flat-gesture-tiny.png"),
10doc = ::embed_doc_image::embed_image!("dancing-ferris", "images/dancing-ferris-tiny.gif"),
11doc = ::embed_doc_image::embed_image!("corro", "images/corro.svg")))]
12#![cfg_attr(
13    not(feature = "doc-images"),
14    doc = "**Doc images not enabled**. Compile with feature `doc-images` and Rust version >= 1.54 \
15           to enable."
16)]
17//!
18//! This crate contains no functionality, it is merely a demonstration of how to use
19//! [embed-doc-image](https://crates.io/crates/embed-doc-image) to embed images local to the
20//! repository that work across both [docs.rs](https://docs.rs) and
21//! local documentation. The motivation for this crate is
22//! [rustdoc's inability to include local images](https://github.com/rust-lang/rust/issues/32104)
23//! in a way that consistently works across local copies of the repository and `docs.rs`.
24//!
25//! See [the documentation](https://docs.rs/embed-doc-image) for more information.
26//! In addition, you are encouraged to browse the source code for this showcase crate to see a
27//! fleshed out example of how the solution works.
28//!
29//! In addition to serving as a showcase, this crate is used to verify that the solution indeed
30//! works across both local installations and `docs.rs`.
31//! This is necessary because a proc macro crate cannot use its own macros in its own documentation.
32//!
33//! `embed-doc-image` should work across the usual web-supported file types
34//! (jpg, png, svg, gif, bmp). If you find that it does not work with your files, please
35//! file an issue.
36//!
37//! The below Ferris images are courtesy of [rustacean.net](https://rustacean.net).
38//!
39//! ![Original Ferris][ferris]
40//!
41//! ![Ferris making gesture][ferris-gesture]
42//!
43//! ![Corro][corro]
44//!
45//! ![Dancing Ferris][dancing-ferris]
46//!
47use embed_doc_image::embed_doc_image;
48
49/// Test that images render in function docs.
50///
51/// ![Original Ferris][ferris] ![Ferris makes gesture][ferris-gesture]
52///
53/// Some more docs.
54///
55/// ![Corro][corro] ![Dancing Ferris][dancing-ferris]
56#[embed_doc_image("ferris", "images/rustacean-orig-noshadow-tiny.png")]
57#[embed_doc_image("ferris-gesture", "images/rustacean-flat-gesture-tiny.png")]
58#[embed_doc_image("dancing-ferris", "images/dancing-ferris-tiny.gif")]
59#[embed_doc_image("corro", "images/corro.svg")]
60pub fn function_docs_work() {}
61
62/// Test that images render in module docs.
63///
64/// ![Original Ferris][ferris] ![Ferris makes gesture][ferris-gesture]
65///
66/// Some more docs.
67///
68/// ![Corro][corro] ![Dancing Ferris][dancing-ferris]
69#[embed_doc_image("ferris", "images/rustacean-orig-noshadow-tiny.png")]
70#[embed_doc_image("ferris-gesture", "images/rustacean-flat-gesture-tiny.png")]
71#[embed_doc_image("dancing-ferris", "images/dancing-ferris-tiny.gif")]
72#[embed_doc_image("corro", "images/corro.svg")]
73pub mod module_docs_work {}
74
75/// Test that images render in macro docs.
76///
77/// ![Original Ferris][ferris] ![Ferris makes gesture][ferris-gesture]
78///
79/// Some more docs.
80///
81/// ![Corro][corro] ![Dancing Ferris][dancing-ferris]
82#[embed_doc_image("ferris", "images/rustacean-orig-noshadow-tiny.png")]
83#[embed_doc_image("ferris-gesture", "images/rustacean-flat-gesture-tiny.png")]
84#[embed_doc_image("dancing-ferris", "images/dancing-ferris-tiny.gif")]
85#[embed_doc_image("corro", "images/corro.svg")]
86#[macro_export]
87macro_rules! macro_docs_work {
88    () => {};
89}
90
91/// Test that images render in struct docs.
92///
93/// ![Original Ferris][ferris] ![Ferris makes gesture][ferris-gesture]
94///
95/// Some more docs.
96///
97/// ![Corro][corro] ![Dancing Ferris][dancing-ferris]
98#[embed_doc_image("ferris", "images/rustacean-orig-noshadow-tiny.png")]
99#[embed_doc_image("ferris-gesture", "images/rustacean-flat-gesture-tiny.png")]
100#[embed_doc_image("dancing-ferris", "images/dancing-ferris-tiny.gif")]
101#[embed_doc_image("corro", "images/corro.svg")]
102pub struct StructDocsWork {}
103
104/// Test that images render in trait docs.
105///
106/// ![Original Ferris][ferris] ![Ferris makes gesture][ferris-gesture]
107///
108/// Some more docs.
109///
110/// ![Corro][corro] ![Dancing Ferris][dancing-ferris]
111#[embed_doc_image("ferris", "images/rustacean-orig-noshadow-tiny.png")]
112#[embed_doc_image("ferris-gesture", "images/rustacean-flat-gesture-tiny.png")]
113#[embed_doc_image("dancing-ferris", "images/dancing-ferris-tiny.gif")]
114#[embed_doc_image("corro", "images/corro.svg")]
115pub trait TraitDocsWork {}
116
117/// Test that images render in type docs.
118///
119/// ![Original Ferris][ferris] ![Ferris makes gesture][ferris-gesture]
120///
121/// Some more docs.
122///
123/// ![Corro][corro] ![Dancing Ferris][dancing-ferris]
124#[embed_doc_image("ferris", "images/rustacean-orig-noshadow-tiny.png")]
125#[embed_doc_image("ferris-gesture", "images/rustacean-flat-gesture-tiny.png")]
126#[embed_doc_image("dancing-ferris", "images/dancing-ferris-tiny.gif")]
127#[embed_doc_image("corro", "images/corro.svg")]
128pub type TypeAliasDocsWork = f64;
embed_doc_image_showcase/lib.rs

embed_doc_image_showcase/
lib.rs
