rune/doc/
artifacts.rs

Help
1use rust_alloc::string::ToString;
2
3use std::fs;
4use std::io;
5
6use rust_alloc::borrow::ToOwned;
7use std::path::Path;
8
9use crate::alloc::borrow::Cow;
10use crate::alloc::{String, Vec};
11use crate::runtime::Protocol;
12use crate::ItemBuf;
13
14use anyhow::{Context as _, Error, Result};
15use base64::display::Base64Display;
16use base64::engine::general_purpose::URL_SAFE_NO_PAD;
17use relative_path::{RelativePath, RelativePathBuf};
18use sha2::{Digest, Sha256};
19
20/// Test parameters.
21#[derive(Debug, Default, Clone, Copy)]
22pub(crate) struct TestParams {
23    /// If the test should not run.
24    pub(crate) no_run: bool,
25    /// If the test should panic.
26    pub(crate) should_panic: bool,
27    /// Ignore the test.
28    pub(crate) ignore: bool,
29}
30
31/// The kind of a test.
32#[derive(Default, Debug, Clone, Copy)]
33pub(crate) enum TestKind {
34    /// The test originates from a free function.
35    #[default]
36    Free,
37    /// The test originates from a protocol function.
38    Protocol(&'static Protocol),
39}
40
41/// A discovered test.
42pub(crate) struct Test {
43    /// Item of the test.
44    pub(crate) item: ItemBuf,
45    /// The kind of a test.
46    pub(crate) kind: TestKind,
47    /// Lines that make up the tests.
48    pub(crate) content: String,
49    /// Test parameters.
50    pub(crate) params: TestParams,
51}
52
53/// A collection of artifacts produced by a documentation build.
54///
55/// This can be disabled through the [`AssetsQueue::disabled`] constructor in
56/// case you don't want any static assets to be built.
57pub(crate) struct Artifacts {
58    pub(crate) enabled: bool,
59    assets: Vec<Asset>,
60    tests: Vec<Test>,
61}
62
63impl Artifacts {
64    /// Construct a new assets queue.
65    pub(crate) fn new() -> Self {
66        Self {
67            enabled: true,
68            assets: Vec::new(),
69            tests: Vec::new(),
70        }
71    }
72
73    /// Build a disabled assets queue.
74    pub(crate) fn without_assets() -> Self {
75        Self {
76            enabled: false,
77            assets: Vec::new(),
78            tests: Vec::new(),
79        }
80    }
81
82    /// Set captures tests.
83    pub(crate) fn set_tests(&mut self, tests: Vec<Test>) {
84        self.tests = tests;
85    }
86
87    /// Iterate over assets produced by this documentation build.
88    ///
89    /// This is always empty if the [`Artifacts::without_assets`] constructor
90    /// was used.
91    pub(crate) fn assets(&self) -> impl Iterator<Item = &Asset> {
92        self.assets.iter()
93    }
94
95    /// Iterate over tests produced by this documentation build.
96    pub(crate) fn tests(&self) -> impl Iterator<Item = &Test> {
97        self.tests.iter()
98    }
99
100    /// Define an asset artifact.
101    pub(crate) fn asset<P, F>(
102        &mut self,
103        hash: bool,
104        path: &P,
105        content: F,
106    ) -> Result<RelativePathBuf>
107    where
108        P: ?Sized + AsRef<RelativePath>,
109        F: FnOnce() -> Result<Cow<'static, [u8]>>,
110    {
111        if !self.enabled {
112            return Ok(path.as_ref().to_owned());
113        }
114
115        let content = content().context("Building asset content")?;
116
117        let path = if hash {
118            let mut hasher = Sha256::new();
119            hasher.update(content.as_ref());
120            let result = hasher.finalize();
121            let hash = Base64Display::new(&result[..], &URL_SAFE_NO_PAD);
122
123            let path = path.as_ref();
124            let stem = path.file_stem().context("Missing file stem")?;
125            let ext = path.extension().context("Missing file extension")?;
126            path.with_file_name(format!("{stem}-{hash}.{ext}"))
127        } else {
128            path.as_ref().to_owned()
129        };
130
131        self.assets.try_push(Asset {
132            path: path.clone(),
133            content,
134        })?;
135
136        Ok(path)
137    }
138}
139
140/// Asset builder.
141pub(crate) struct Asset {
142    path: RelativePathBuf,
143    content: Cow<'static, [u8]>,
144}
145
146impl Asset {
147    /// Build the given asset.
148    pub(crate) fn build(&self, root: &Path) -> Result<()> {
149        let p = self.path.to_path(root);
150        tracing::info!("Writing: {}", p.display());
151        ensure_parent_dir(&p)?;
152        fs::write(&p, &self.content).with_context(|| p.display().to_string())?;
153        Ok(())
154    }
155}
156
157/// Ensure parent dir exists.
158fn ensure_parent_dir(path: &Path) -> Result<()> {
159    if let Some(p) = path.parent() {
160        if p.is_dir() {
161            return Ok(());
162        }
163
164        tracing::info!("create dir: {}", p.display());
165
166        match fs::create_dir_all(p) {
167            Ok(()) => {}
168            Err(e) if e.kind() == io::ErrorKind::AlreadyExists => {}
169            Err(e) => return Err(Error::from(e)).context(p.display().to_string()),
170        }
171    }
172
173    Ok(())
174}
rune/doc/artifacts.rs

rune/doc/
artifacts.rs
