rune/doc/
build.rs

Help
1mod js;
2mod type_;
3
4use core::fmt;
5use core::str;
6
7use rust_alloc::string::ToString;
8
9use anyhow::{anyhow, bail, Context as _, Result};
10use relative_path::{RelativePath, RelativePathBuf};
11use serde::{Serialize, Serializer};
12use syntect::highlighting::ThemeSet;
13use syntect::html;
14use syntect::parsing::SyntaxSet;
15
16use crate as rune;
17use crate::alloc::borrow::Cow;
18use crate::alloc::fmt::TryWrite;
19use crate::alloc::prelude::*;
20use crate::alloc::{self, HashSet, VecDeque};
21use crate::compile::meta;
22use crate::doc::artifacts::{Test, TestKind};
23use crate::doc::context::{Function, Kind, Meta, Signature};
24use crate::doc::templating;
25use crate::doc::{Artifacts, Context, Visitor};
26use crate::item::ComponentRef;
27use crate::runtime::OwnedTuple;
28use crate::std::borrow::ToOwned;
29use crate::{Hash, Item, TypeHash};
30
31use super::markdown;
32
33// InspiredGitHub
34// Solarized (dark)
35// Solarized (light)
36// base16-eighties.dark
37// base16-mocha.dark
38// base16-ocean.dark
39// base16-ocean.light
40const THEME: &str = "base16-eighties.dark";
41const RUNEDOC_CSS: &str = "runedoc.css";
42
43pub(crate) struct Builder<'m> {
44    state: State<'m>,
45    builder: rust_alloc::boxed::Box<dyn FnOnce(&Ctxt<'_, '_>) -> Result<String> + 'm>,
46}
47
48impl<'m> Builder<'m> {
49    fn new<B>(cx: &Ctxt<'_, 'm>, builder: B) -> alloc::Result<Self>
50    where
51        B: FnOnce(&Ctxt<'_, '_>) -> Result<String> + 'm,
52    {
53        Ok(Self {
54            state: cx.state.try_clone()?,
55            builder: rust_alloc::boxed::Box::new(builder),
56        })
57    }
58}
59
60mod embed {
61    #[cfg(debug_assertions)]
62    use rust_alloc::boxed::Box;
63    #[cfg(debug_assertions)]
64    use rust_alloc::string::String;
65
66    use rust_embed::RustEmbed;
67
68    #[derive(RustEmbed)]
69    #[folder = "src/doc/static"]
70    pub(super) struct Assets;
71}
72
73/// Build documentation based on the given context and visitors.
74pub(crate) fn build(
75    name: &str,
76    artifacts: &mut Artifacts,
77    context: Option<&crate::Context>,
78    visitors: &[Visitor],
79) -> Result<()> {
80    let context = Context::new(context, visitors);
81
82    let paths = templating::Paths::default();
83
84    let partials = [("layout", asset_str("layout.html.hbs")?)];
85
86    let templating = templating::Templating::new(partials, paths.clone())?;
87
88    let mut fonts = Vec::new();
89    let mut css = Vec::new();
90    let mut js = Vec::new();
91
92    for file in embed::Assets::iter() {
93        let path = RelativePath::new(file.as_ref());
94
95        let out = match path.extension() {
96            Some("woff2") => &mut fonts,
97            Some("css") => &mut css,
98            Some("js") => &mut js,
99            _ => continue,
100        };
101
102        let file = embed::Assets::get(file.as_ref()).context("missing asset")?;
103
104        let builder_path = artifacts.asset(true, path, move || {
105            let data = Cow::try_from(file.data)?;
106            Ok(data)
107        })?;
108
109        paths.insert(path.as_str(), builder_path.as_str())?;
110        out.try_push(builder_path)?;
111    }
112
113    let syntax_css = artifacts.asset(true, "syntax.css", || {
114        let theme_set = ThemeSet::load_defaults();
115        let theme = theme_set.themes.get(THEME).context("missing theme")?;
116        let content = String::try_from(html::css_for_theme_with_class_style(
117            theme,
118            html::ClassStyle::Spaced,
119        )?)?;
120        Ok(content.into_bytes().into())
121    })?;
122
123    paths.insert("syntax.css", syntax_css.as_str())?;
124    css.try_push(syntax_css)?;
125
126    let runedoc_css = artifacts.asset(true, RUNEDOC_CSS, || {
127        let runedoc = compile(&templating, "runedoc.css.hbs")?;
128        let string = runedoc.render(&())?;
129        Ok(string.into_bytes().into())
130    })?;
131
132    paths.insert(RUNEDOC_CSS, runedoc_css.as_str())?;
133    css.try_push(runedoc_css)?;
134
135    // Collect an ordered set of modules, so we have a baseline of what to render when.
136    let mut initial = Vec::new();
137    let mut initial_seen = HashSet::new();
138
139    for item in context.iter_modules() {
140        let item = item?;
141
142        let meta = context
143            .meta(&item)?
144            .into_iter()
145            .find(|m| matches!(&m.kind, Kind::Module))
146            .with_context(|| anyhow!("Missing meta for {item}"))?;
147
148        if !initial_seen.try_insert(meta.hash)? {
149            continue;
150        }
151
152        initial.try_push((Build::Module, meta))?;
153    }
154
155    initial.sort_by_key(|(_, meta)| meta.item);
156
157    let search_index = RelativePath::new("index.js");
158    let root_index = RelativePath::new("index.html");
159
160    let mut cx = Ctxt {
161        state: State::default(),
162        index: Vec::new(),
163        name,
164        context: &context,
165        search_index: Some(search_index),
166        root_index,
167        fonts: &fonts,
168        css: &css,
169        js: &js,
170        index_template: compile(&templating, "index.html.hbs")?,
171        module_template: compile(&templating, "module.html.hbs")?,
172        type_template: compile(&templating, "type.html.hbs")?,
173        macro_template: compile(&templating, "macro.html.hbs")?,
174        function_template: compile(&templating, "function.html.hbs")?,
175        syntax_set: artifacts.enabled.then(SyntaxSet::load_defaults_newlines),
176        tests: Vec::new(),
177    };
178
179    let mut queue = initial.into_iter().try_collect::<VecDeque<_>>()?;
180
181    let mut modules = Vec::new();
182    let mut builders = Vec::new();
183    let mut visited = HashSet::new();
184
185    while let Some((build, meta)) = queue.pop_front() {
186        if !visited.try_insert((build, meta.hash))? {
187            tracing::error!(?build, ?meta.item, "Already visited");
188            continue;
189        }
190
191        cx.set_path(meta)?;
192
193        tracing::trace!(?build, ?meta.item, ?cx.state.path, "Building");
194
195        match build {
196            Build::Type => {
197                let (builder, items) = self::type_::build(&mut cx, "Type", "type", meta)?;
198                builders.try_push(builder)?;
199                cx.index.try_extend(items)?;
200            }
201            Build::Trait => {
202                let (builder, items) = self::type_::build(&mut cx, "Trait", "trait", meta)?;
203                builders.try_push(builder)?;
204                cx.index.try_extend(items)?;
205            }
206            Build::Struct => {
207                let (builder, index) = self::type_::build(&mut cx, "Struct", "struct", meta)?;
208                builders.try_push(builder)?;
209                cx.index.try_extend(index)?;
210            }
211            Build::Enum => {
212                let (builder, index) = self::type_::build(&mut cx, "Enum", "enum", meta)?;
213                builders.try_push(builder)?;
214                cx.index.try_extend(index)?;
215            }
216            Build::Macro => {
217                builders.try_push(build_macro(&mut cx, meta)?)?;
218            }
219            Build::Function => {
220                builders.try_push(build_function(&mut cx, meta)?)?;
221            }
222            Build::Module => {
223                builders.try_push(module(&mut cx, meta, &mut queue)?)?;
224                modules.try_push((meta.item, cx.state.path.clone()))?;
225            }
226        }
227    }
228
229    let search_index_path = artifacts.asset(true, "index.js", || {
230        let content = build_search_index(&cx)?;
231        Ok(content.into_bytes().into())
232    })?;
233
234    cx.search_index = Some(&search_index_path);
235
236    cx.state.path = RelativePath::new("index.html").to_owned();
237    builders.try_push(build_index(&cx, modules)?)?;
238
239    for builder in builders {
240        cx.state = builder.state;
241        artifacts.asset(false, &cx.state.path, || {
242            Ok((builder.builder)(&cx)?.into_bytes().into())
243        })?;
244    }
245
246    artifacts.set_tests(cx.tests);
247    Ok(())
248}
249
250fn build_search_index(cx: &Ctxt) -> Result<String> {
251    let mut s = String::new();
252    write!(s, "window.INDEX = [")?;
253    let mut it = cx.index.iter();
254
255    while let Some(IndexEntry {
256        path,
257        item,
258        kind,
259        doc,
260    }) = it.next()
261    {
262        write!(s, "[\"{path}\",\"{item}\",\"{kind}\",\"")?;
263
264        if let Some(doc) = doc {
265            js::encode_quoted(&mut s, doc)?;
266        }
267
268        write!(s, "\"]")?;
269
270        if it.clone().next().is_some() {
271            write!(s, ",")?;
272        }
273    }
274
275    write!(s, "];")?;
276    writeln!(s)?;
277    Ok(s)
278}
279
280#[derive(Serialize)]
281struct Shared<'a> {
282    data_path: Option<&'a RelativePath>,
283    search_index: Option<RelativePathBuf>,
284    root_index: RelativePathBuf,
285    fonts: Vec<RelativePathBuf>,
286    css: Vec<RelativePathBuf>,
287    js: Vec<RelativePathBuf>,
288}
289
290#[derive(Debug, Clone, Copy)]
291pub(crate) enum ItemKind {
292    Type,
293    Struct,
294    Enum,
295    Module,
296    Macro,
297    Function,
298    Trait,
299}
300
301impl fmt::Display for ItemKind {
302    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
303        match self {
304            ItemKind::Type => "type".fmt(f),
305            ItemKind::Struct => "struct".fmt(f),
306            ItemKind::Enum => "enum".fmt(f),
307            ItemKind::Module => "module".fmt(f),
308            ItemKind::Macro => "macro".fmt(f),
309            ItemKind::Function => "function".fmt(f),
310            ItemKind::Trait => "trait".fmt(f),
311        }
312    }
313}
314
315pub(crate) enum IndexKind {
316    Item(ItemKind),
317    Method,
318    Variant,
319}
320
321impl fmt::Display for IndexKind {
322    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
323        match self {
324            IndexKind::Item(item) => item.fmt(f),
325            IndexKind::Method => "method".fmt(f),
326            IndexKind::Variant => "variant".fmt(f),
327        }
328    }
329}
330
331pub(crate) struct IndexEntry<'m> {
332    pub(crate) path: RelativePathBuf,
333    pub(crate) item: Cow<'m, Item>,
334    pub(crate) kind: IndexKind,
335    pub(crate) doc: Option<String>,
336}
337
338#[derive(Default, TryClone)]
339pub(crate) struct State<'m> {
340    #[try_clone(with = RelativePathBuf::clone)]
341    path: RelativePathBuf,
342    #[try_clone(copy)]
343    item: &'m Item,
344    #[try_clone(copy)]
345    kind: TestKind,
346}
347
348pub(crate) struct Ctxt<'a, 'm> {
349    state: State<'m>,
350    /// A collection of all items visited.
351    index: Vec<IndexEntry<'m>>,
352    name: &'a str,
353    context: &'a Context<'m>,
354    search_index: Option<&'a RelativePath>,
355    root_index: &'a RelativePath,
356    fonts: &'a [RelativePathBuf],
357    css: &'a [RelativePathBuf],
358    js: &'a [RelativePathBuf],
359    index_template: templating::Template,
360    module_template: templating::Template,
361    type_template: templating::Template,
362    macro_template: templating::Template,
363    function_template: templating::Template,
364    syntax_set: Option<SyntaxSet>,
365    tests: Vec<Test>,
366}
367
368impl<'m> Ctxt<'_, 'm> {
369    fn set_path(&mut self, meta: Meta<'m>) -> Result<()> {
370        let item_kind = match &meta.kind {
371            Kind::Type => ItemKind::Type,
372            Kind::Struct => ItemKind::Struct,
373            Kind::Enum => ItemKind::Enum,
374            Kind::Macro => ItemKind::Macro,
375            Kind::Function(..) => ItemKind::Function,
376            Kind::Module => ItemKind::Module,
377            Kind::Trait => ItemKind::Trait,
378            kind => bail!("Cannot set path for {kind:?}"),
379        };
380
381        self.state.kind = TestKind::default();
382        self.state.path = RelativePathBuf::new();
383        self.state.item = meta.item;
384
385        build_item_path(self.name, meta.item, item_kind, &mut self.state.path)?;
386
387        let doc = self.render_line_docs(meta, meta.docs.get(..1).unwrap_or_default())?;
388
389        self.index.try_push(IndexEntry {
390            path: self.state.path.clone(),
391            item: Cow::Borrowed(meta.item),
392            kind: IndexKind::Item(item_kind),
393            doc,
394        })?;
395
396        Ok(())
397    }
398
399    fn dir(&self) -> &RelativePath {
400        self.state.path.parent().unwrap_or(RelativePath::new(""))
401    }
402
403    fn shared(&self) -> Result<Shared<'_>> {
404        let dir = self.dir();
405
406        Ok(Shared {
407            data_path: self.state.path.parent(),
408            search_index: self.search_index.map(|p| dir.relative(p)),
409            root_index: dir.relative(self.root_index),
410            fonts: self.fonts.iter().map(|f| dir.relative(f)).try_collect()?,
411            css: self.css.iter().map(|f| dir.relative(f)).try_collect()?,
412            js: self.js.iter().map(|f| dir.relative(f)).try_collect()?,
413        })
414    }
415
416    /// Render rust code.
417    fn render_code<I>(&self, lines: I) -> Result<String>
418    where
419        I: IntoIterator,
420        I::Item: AsRef<str>,
421    {
422        match &self.syntax_set {
423            Some(syntax_set) => {
424                let syntax = match syntax_set.find_syntax_by_token(self::markdown::RUST_TOKEN) {
425                    Some(syntax) => syntax,
426                    None => syntax_set.find_syntax_plain_text(),
427                };
428
429                Ok(try_format!(
430                    "<pre><code class=\"language-rune\">{}</code></pre>",
431                    markdown::render_code_by_syntax(syntax_set, syntax, lines, None)?
432                ))
433            }
434            None => Ok(try_format!(
435                "<pre><code class=\"language-rune\">{}</code></pre>",
436                markdown::render_code_without_syntax(lines, None)?
437            )),
438        }
439    }
440
441    /// Render an optional return type parameter.
442    ///
443    /// Returning `None` indicates that the return type is the default return
444    /// type, which is `()`.
445    fn return_type(&self, ty: &meta::DocType) -> Result<Option<String>> {
446        match *ty {
447            meta::DocType {
448                base, ref generics, ..
449            } if OwnedTuple::HASH == base && generics.is_empty() => Ok(None),
450            meta::DocType {
451                base, ref generics, ..
452            } => Ok(Some(self.link(base, None, generics)?)),
453        }
454    }
455
456    /// Render line docs.
457    fn render_line_docs<S>(&mut self, meta: Meta<'_>, docs: &[S]) -> Result<Option<String>>
458    where
459        S: AsRef<str>,
460    {
461        self.render_docs(meta, docs, false)
462    }
463
464    /// Render documentation.
465    fn render_docs<S>(
466        &mut self,
467        meta: Meta<'_>,
468        docs: &[S],
469        capture_tests: bool,
470    ) -> Result<Option<String>>
471    where
472        S: AsRef<str>,
473    {
474        use pulldown_cmark::{BrokenLink, Options, Parser};
475
476        if docs.is_empty() {
477            return Ok(None);
478        }
479
480        let mut input = String::new();
481
482        for line in docs {
483            let line = line.as_ref();
484            let line = line.strip_prefix(' ').unwrap_or(line);
485            input.try_push_str(line)?;
486            input.try_push('\n')?;
487        }
488
489        let mut o = String::new();
490        write!(o, "<div class=\"docs\">")?;
491        let mut options = Options::empty();
492        options.insert(Options::ENABLE_STRIKETHROUGH);
493
494        let mut link_error = None;
495
496        let mut callback = |link: BrokenLink<'_>| {
497            let (path, title) = match self.link_callback(meta, link.reference.as_ref()) {
498                Ok(out) => out?,
499                Err(error) => {
500                    link_error = Some(error);
501                    return None;
502                }
503            };
504
505            Some((path.to_string().into(), title.into_std().into()))
506        };
507
508        let iter = Parser::new_with_broken_link_callback(&input, options, Some(&mut callback));
509
510        let mut tests = Vec::new();
511
512        markdown::push_html(
513            self.syntax_set.as_ref(),
514            &mut o,
515            iter,
516            capture_tests.then_some(&mut tests),
517        )?;
518
519        if let Some(error) = link_error {
520            return Err(error);
521        }
522
523        for (content, params) in tests {
524            self.tests.try_push(Test {
525                item: self.state.item.try_to_owned()?,
526                kind: self.state.kind,
527                content,
528                params,
529            })?;
530        }
531
532        write!(o, "</div>")?;
533        Ok(Some(o))
534    }
535
536    #[inline]
537    fn item_path(&self, item: &Item, kind: ItemKind) -> Result<RelativePathBuf> {
538        let mut path = RelativePathBuf::new();
539        build_item_path(self.name, item, kind, &mut path)?;
540        Ok(self.dir().relative(path))
541    }
542
543    /// Build backlinks for the current item.
544    fn module_path_html(&self, meta: Meta<'_>, is_module: bool) -> Result<String> {
545        fn unqualified_component<'a>(c: &'a ComponentRef<'_>) -> &'a dyn fmt::Display {
546            match c {
547                ComponentRef::Crate(name) => name,
548                ComponentRef::Str(name) => name,
549                c => c,
550            }
551        }
552
553        let mut module = Vec::new();
554
555        let mut iter = meta.item.iter();
556
557        while iter.next_back().is_some() {
558            if let Some(c) = iter.as_item().last() {
559                let name: &dyn fmt::Display = unqualified_component(&c);
560                let url = self.item_path(iter.as_item(), ItemKind::Module)?;
561                module.try_push(try_format!("<a class=\"module\" href=\"{url}\">{name}</a>"))?;
562            }
563        }
564
565        module.reverse();
566
567        if is_module {
568            if let Some(c) = meta.item.last() {
569                let name: &dyn fmt::Display = unqualified_component(&c);
570                module.try_push(try_format!("<span class=\"module\">{name}</span>"))?;
571            }
572        }
573
574        let mut string = String::new();
575
576        let mut it = module.into_iter();
577
578        let last = it.next_back();
579
580        for c in it {
581            string.try_push_str(c.as_str())?;
582            string.try_push_str("::")?;
583        }
584
585        if let Some(c) = last {
586            string.try_push_str(c.as_str())?;
587        }
588
589        Ok(string)
590    }
591
592    /// Convert a hash into a link.
593    fn link(&self, hash: Hash, text: Option<&str>, generics: &[meta::DocType]) -> Result<String> {
594        let mut s = String::new();
595        self.write_link(&mut s, hash, text, generics)?;
596        Ok(s)
597    }
598
599    /// Write a placeholder for the `any` type.
600    fn write_any(&self, o: &mut dyn TryWrite) -> Result<()> {
601        write!(o, "<span class=\"any\">any</span>")?;
602        Ok(())
603    }
604
605    /// Convert a hash into a link.
606    fn write_link(
607        &self,
608        o: &mut dyn TryWrite,
609        hash: Hash,
610        text: Option<&str>,
611        generics: &[meta::DocType],
612    ) -> Result<()> {
613        fn into_item_kind(meta: Meta<'_>) -> Option<ItemKind> {
614            match &meta.kind {
615                Kind::Type => Some(ItemKind::Type),
616                Kind::Struct => Some(ItemKind::Struct),
617                Kind::Enum => Some(ItemKind::Enum),
618                Kind::Function { .. } => Some(ItemKind::Function),
619                _ => None,
620            }
621        }
622
623        let Some(hash) = hash.as_non_empty() else {
624            self.write_any(o)?;
625            return Ok(());
626        };
627
628        if OwnedTuple::HASH == hash && text.is_none() {
629            write!(o, "(")?;
630            self.write_generics(o, generics)?;
631            write!(o, ")")?;
632            return Ok(());
633        }
634
635        let mut it = self
636            .context
637            .meta_by_hash(hash)?
638            .into_iter()
639            .flat_map(|m| Some((m, into_item_kind(m)?)));
640
641        let outcome = 'out: {
642            let Some((meta, kind)) = it.next() else {
643                tracing::warn!(?hash, "No link for hash");
644
645                for _meta in self.context.meta_by_hash(hash)? {
646                    tracing::warn!("Candidate: {:?}", _meta.kind);
647                }
648
649                break 'out (None, None, text);
650            };
651
652            let text = match text {
653                Some(text) => Some(text),
654                None => meta.item.last().and_then(|c| c.as_str()),
655            };
656
657            (Some(self.item_path(meta.item, kind)?), Some(kind), text)
658        };
659
660        let (path, kind, text) = outcome;
661
662        let text: &dyn fmt::Display = match &text {
663            Some(text) => text,
664            None => &hash,
665        };
666
667        if let (Some(kind), Some(path)) = (kind, path) {
668            write!(o, "<a class=\"{kind}\" href=\"{path}\">{text}</a>")?;
669        } else {
670            write!(o, "{text}")?;
671        }
672
673        if !generics.is_empty() {
674            write!(o, "&lt;")?;
675            self.write_generics(o, generics)?;
676            write!(o, "&gt;")?;
677        }
678
679        Ok(())
680    }
681
682    fn write_generics(&self, o: &mut dyn TryWrite, generics: &[meta::DocType]) -> Result<()> {
683        let mut it = generics.iter().peekable();
684
685        while let Some(ty) = it.next() {
686            self.write_link(o, ty.base, None, &ty.generics)?;
687
688            if it.peek().is_some() {
689                write!(o, ", ")?;
690            }
691        }
692
693        Ok(())
694    }
695
696    /// Coerce args into string.
697    fn args_to_string(
698        &self,
699        sig: Signature,
700        arguments: Option<&[meta::DocArgument]>,
701    ) -> Result<String> {
702        let mut string = String::new();
703
704        let Some(arguments) = arguments else {
705            match sig {
706                Signature::Function => {
707                    let mut string = String::new();
708                    write!(string, "..")?;
709                    return Ok(string);
710                }
711                Signature::Instance => {
712                    let mut string = String::new();
713                    write!(string, "self, ..")?;
714                    return Ok(string);
715                }
716            }
717        };
718
719        let mut it = arguments.iter().peekable();
720
721        while let Some(arg) = it.next() {
722            if matches!(sig, Signature::Instance) && arg.name.is_self() {
723                if let Some(hash) = arg.base.as_non_empty() {
724                    self.write_link(&mut string, hash, Some("self"), &[])?;
725                } else {
726                    write!(string, "self")?;
727                }
728            } else {
729                write!(string, "{}", arg.name)?;
730                string.try_push_str(": ")?;
731                self.write_link(&mut string, arg.base, None, &arg.generics)?;
732            }
733
734            if it.peek().is_some() {
735                write!(string, ", ")?;
736            }
737        }
738
739        Ok(string)
740    }
741
742    fn link_callback(
743        &self,
744        meta: Meta<'_>,
745        link: &str,
746    ) -> Result<Option<(RelativePathBuf, String)>> {
747        enum Flavor {
748            Any,
749            Macro,
750            Function,
751        }
752
753        impl Flavor {
754            fn is_struct(&self) -> bool {
755                matches!(self, Flavor::Any)
756            }
757
758            fn is_enum(&self) -> bool {
759                matches!(self, Flavor::Any)
760            }
761
762            fn is_macro(&self) -> bool {
763                matches!(self, Flavor::Any | Flavor::Macro)
764            }
765
766            fn is_function(&self) -> bool {
767                matches!(self, Flavor::Any | Flavor::Function)
768            }
769        }
770
771        fn flavor(link: &str) -> (&str, Flavor) {
772            if let Some(link) = link.strip_suffix('!') {
773                return (link, Flavor::Macro);
774            }
775
776            if let Some(link) = link.strip_suffix("()") {
777                return (link, Flavor::Function);
778            }
779
780            (link, Flavor::Any)
781        }
782
783        let link = link.trim_matches(|c| matches!(c, '`'));
784        let (link, flavor) = flavor(link);
785
786        let item = if matches!(meta.kind, Kind::Module) {
787            meta.item.join([link])?
788        } else {
789            let Some(parent) = meta.item.parent() else {
790                return Ok(None);
791            };
792
793            parent.join([link])?
794        };
795
796        let item_path = 'out: {
797            let mut alts = Vec::new();
798
799            for meta in self.context.meta(&item)? {
800                alts.try_push(match meta.kind {
801                    Kind::Struct if flavor.is_struct() => ItemKind::Struct,
802                    Kind::Enum if flavor.is_enum() => ItemKind::Enum,
803                    Kind::Macro if flavor.is_macro() => ItemKind::Macro,
804                    Kind::Function(_) if flavor.is_function() => ItemKind::Function,
805                    _ => {
806                        continue;
807                    }
808                })?;
809            }
810
811            match &alts[..] {
812                [] => {
813                    tracing::warn!(?link, "Bad link, no items found");
814                }
815                [out] => break 'out *out,
816                _items => {
817                    tracing::warn!(?link, items = ?_items, "Bad link, got multiple items");
818                }
819            }
820
821            return Ok(None);
822        };
823
824        let path = self.item_path(&item, item_path)?;
825        let title = try_format!("{item_path} {link}");
826        Ok(Some((path, title)))
827    }
828}
829
830#[derive(Clone, Copy, Hash, PartialEq, Eq, Debug)]
831enum Build {
832    Type,
833    Struct,
834    Enum,
835    Macro,
836    Function,
837    Module,
838    Trait,
839}
840
841/// Get an asset as a string.
842fn asset_str(path: &str) -> Result<Cow<'static, str>> {
843    let asset = embed::Assets::get(path).with_context(|| anyhow!("{path}: missing asset"))?;
844
845    let data = match asset.data {
846        rust_alloc::borrow::Cow::Borrowed(data) => {
847            Cow::Borrowed(str::from_utf8(data).with_context(|| anyhow!("{path}: not utf-8"))?)
848        }
849        rust_alloc::borrow::Cow::Owned(data) => Cow::Owned(
850            String::from_utf8(data.try_into()?).with_context(|| anyhow!("{path}: not utf-8"))?,
851        ),
852    };
853
854    Ok(data)
855}
856
857/// Compile a template.
858fn compile(templating: &templating::Templating, path: &str) -> Result<templating::Template> {
859    let template = asset_str(path)?;
860    templating.compile(template.as_ref())
861}
862
863#[tracing::instrument(skip_all)]
864fn build_index<'m>(
865    cx: &Ctxt<'_, 'm>,
866    mods: Vec<(&'m Item, RelativePathBuf)>,
867) -> Result<Builder<'m>> {
868    #[derive(Serialize)]
869    struct Params<'a> {
870        #[serde(flatten)]
871        shared: Shared<'a>,
872        modules: Vec<Module<'a>>,
873    }
874
875    #[derive(Serialize)]
876    struct Module<'a> {
877        #[serde(serialize_with = "serialize_item")]
878        item: &'a Item,
879        path: RelativePathBuf,
880    }
881
882    let mut modules = Vec::new();
883
884    for (item, path) in mods {
885        let mut c = item.iter();
886
887        match c.next() {
888            None => {}
889            Some(ComponentRef::Crate(..)) => {}
890            _ => continue,
891        }
892
893        if c.next().is_some() {
894            continue;
895        }
896
897        modules.try_push(Module { item, path })?;
898    }
899
900    // sort the modules by name
901    modules.sort_by_key(|module| module.item.as_crate().unwrap_or(""));
902
903    Ok(Builder::new(cx, move |cx| {
904        cx.index_template.render(&Params {
905            shared: cx.shared()?,
906            modules,
907        })
908    })?)
909}
910
911/// Build a single module.
912#[tracing::instrument(skip_all)]
913fn module<'m>(
914    cx: &mut Ctxt<'_, 'm>,
915    meta: Meta<'m>,
916    queue: &mut VecDeque<(Build, Meta<'m>)>,
917) -> Result<Builder<'m>> {
918    #[derive(Serialize)]
919    struct Params<'a> {
920        #[serde(flatten)]
921        shared: Shared<'a>,
922        #[serde(serialize_with = "serialize_item")]
923        item: &'a Item,
924        module: String,
925        doc: Option<String>,
926        types: Vec<Type<'a>>,
927        structs: Vec<Struct<'a>>,
928        enums: Vec<Enum<'a>>,
929        macros: Vec<Macro<'a>>,
930        functions: Vec<Function<'a>>,
931        modules: Vec<Module<'a>>,
932        traits: Vec<Trait<'a>>,
933    }
934
935    #[derive(Serialize)]
936    struct Type<'a> {
937        #[serde(serialize_with = "serialize_item")]
938        item: &'a Item,
939        #[serde(serialize_with = "serialize_component_ref")]
940        name: ComponentRef<'a>,
941        path: RelativePathBuf,
942        doc: Option<String>,
943    }
944
945    #[derive(Serialize)]
946    struct Struct<'a> {
947        path: RelativePathBuf,
948        #[serde(serialize_with = "serialize_item")]
949        item: &'a Item,
950        #[serde(serialize_with = "serialize_component_ref")]
951        name: ComponentRef<'a>,
952        doc: Option<String>,
953    }
954
955    #[derive(Serialize)]
956    struct Enum<'a> {
957        path: RelativePathBuf,
958        #[serde(serialize_with = "serialize_item")]
959        item: &'a Item,
960        #[serde(serialize_with = "serialize_component_ref")]
961        name: ComponentRef<'a>,
962        doc: Option<String>,
963    }
964
965    #[derive(Serialize)]
966    struct Macro<'a> {
967        path: RelativePathBuf,
968        #[serde(serialize_with = "serialize_item")]
969        item: &'a Item,
970        #[serde(serialize_with = "serialize_component_ref")]
971        name: ComponentRef<'a>,
972        doc: Option<String>,
973    }
974
975    #[derive(Serialize)]
976    struct Function<'a> {
977        is_async: bool,
978        deprecated: Option<&'a str>,
979        path: RelativePathBuf,
980        #[serde(serialize_with = "serialize_item")]
981        item: &'a Item,
982        #[serde(serialize_with = "serialize_component_ref")]
983        name: ComponentRef<'a>,
984        args: String,
985        doc: Option<String>,
986    }
987
988    #[derive(Serialize)]
989    struct Module<'a> {
990        #[serde(serialize_with = "serialize_item")]
991        item: &'a Item,
992        #[serde(serialize_with = "serialize_component_ref")]
993        name: ComponentRef<'a>,
994        path: RelativePathBuf,
995        doc: Option<String>,
996    }
997
998    #[derive(Serialize)]
999    struct Trait<'a> {
1000        #[serde(serialize_with = "serialize_item")]
1001        item: &'a Item,
1002        #[serde(serialize_with = "serialize_component_ref")]
1003        name: ComponentRef<'a>,
1004        path: RelativePathBuf,
1005        doc: Option<String>,
1006    }
1007
1008    let mut types = Vec::new();
1009    let mut structs = Vec::new();
1010    let mut enums = Vec::new();
1011    let mut macros = Vec::new();
1012    let mut functions = Vec::new();
1013    let mut modules = Vec::new();
1014    let mut traits = Vec::new();
1015
1016    for (_, name) in cx.context.iter_components(meta.item)? {
1017        let item = meta.item.join([name])?;
1018        tracing::trace!(?item, "Looking up");
1019
1020        for m in cx.context.meta(&item)? {
1021            tracing::trace!(?item, ?m.kind, "Found");
1022
1023            match m.kind {
1024                Kind::Type { .. } => {
1025                    queue.try_push_front((Build::Type, m))?;
1026
1027                    types.try_push(Type {
1028                        path: cx.item_path(m.item, ItemKind::Type)?,
1029                        item: m.item,
1030                        name,
1031                        doc: cx.render_line_docs(m, m.docs.get(..1).unwrap_or_default())?,
1032                    })?;
1033                }
1034                Kind::Struct { .. } => {
1035                    queue.try_push_front((Build::Struct, m))?;
1036
1037                    structs.try_push(Struct {
1038                        path: cx.item_path(m.item, ItemKind::Struct)?,
1039                        item: m.item,
1040                        name,
1041                        doc: cx.render_line_docs(m, m.docs.get(..1).unwrap_or_default())?,
1042                    })?;
1043                }
1044                Kind::Enum { .. } => {
1045                    queue.try_push_front((Build::Enum, m))?;
1046
1047                    enums.try_push(Enum {
1048                        path: cx.item_path(m.item, ItemKind::Enum)?,
1049                        item: m.item,
1050                        name,
1051                        doc: cx.render_line_docs(m, m.docs.get(..1).unwrap_or_default())?,
1052                    })?;
1053                }
1054                Kind::Macro => {
1055                    queue.try_push_front((Build::Macro, m))?;
1056
1057                    macros.try_push(Macro {
1058                        path: cx.item_path(m.item, ItemKind::Macro)?,
1059                        item: m.item,
1060                        name,
1061                        doc: cx.render_line_docs(m, m.docs.get(..1).unwrap_or_default())?,
1062                    })?;
1063                }
1064                Kind::Function(f) => {
1065                    if matches!(f.signature, Signature::Instance) {
1066                        continue;
1067                    }
1068
1069                    queue.try_push_front((Build::Function, m))?;
1070
1071                    functions.try_push(Function {
1072                        is_async: f.is_async,
1073                        deprecated: meta.deprecated,
1074                        path: cx.item_path(m.item, ItemKind::Function)?,
1075                        item: m.item,
1076                        name,
1077                        args: cx.args_to_string(f.signature, f.arguments)?,
1078                        doc: cx.render_line_docs(m, m.docs.get(..1).unwrap_or_default())?,
1079                    })?;
1080                }
1081                Kind::Module => {
1082                    // Skip over crate items, since they are added separately.
1083                    if meta.item.is_empty() && m.item.as_crate().is_some() {
1084                        continue;
1085                    }
1086
1087                    queue.try_push_front((Build::Module, m))?;
1088
1089                    let path = cx.item_path(m.item, ItemKind::Module)?;
1090                    let name = m.item.last().context("missing name of module")?;
1091
1092                    // Prevent multiple entries of a module, with no documentation
1093                    modules.retain(|module: &Module<'_>| {
1094                        !(module.name == name && module.doc.is_none())
1095                    });
1096
1097                    modules.try_push(Module {
1098                        item: m.item,
1099                        name,
1100                        path,
1101                        doc: cx.render_line_docs(m, m.docs.get(..1).unwrap_or_default())?,
1102                    })?;
1103                }
1104                Kind::Trait { .. } => {
1105                    queue.try_push_front((Build::Trait, m))?;
1106
1107                    traits.try_push(Trait {
1108                        path: cx.item_path(m.item, ItemKind::Trait)?,
1109                        item: m.item,
1110                        name,
1111                        doc: cx.render_line_docs(m, m.docs.get(..1).unwrap_or_default())?,
1112                    })?;
1113                }
1114                _ => {
1115                    continue;
1116                }
1117            }
1118        }
1119    }
1120
1121    let doc = cx.render_docs(meta, meta.docs, true)?;
1122
1123    Ok(Builder::new(cx, move |cx| {
1124        cx.module_template.render(&Params {
1125            shared: cx.shared()?,
1126            item: meta.item,
1127            module: cx.module_path_html(meta, true)?,
1128            doc,
1129            types,
1130            structs,
1131            enums,
1132            macros,
1133            functions,
1134            modules,
1135            traits,
1136        })
1137    })?)
1138}
1139
1140/// Build a macro.
1141#[tracing::instrument(skip_all)]
1142fn build_macro<'m>(cx: &mut Ctxt<'_, 'm>, meta: Meta<'m>) -> Result<Builder<'m>> {
1143    #[derive(Serialize)]
1144    struct Params<'a> {
1145        #[serde(flatten)]
1146        shared: Shared<'a>,
1147        module: String,
1148        #[serde(serialize_with = "serialize_item")]
1149        item: &'a Item,
1150        #[serde(serialize_with = "serialize_component_ref")]
1151        name: ComponentRef<'a>,
1152        doc: Option<String>,
1153    }
1154
1155    let doc = cx.render_docs(meta, meta.docs, true)?;
1156    let name = meta.item.last().context("Missing macro name")?;
1157
1158    Ok(Builder::new(cx, move |cx| {
1159        cx.macro_template.render(&Params {
1160            shared: cx.shared()?,
1161            module: cx.module_path_html(meta, false)?,
1162            item: meta.item,
1163            name,
1164            doc,
1165        })
1166    })?)
1167}
1168
1169/// Build a function.
1170#[tracing::instrument(skip_all)]
1171fn build_function<'m>(cx: &mut Ctxt<'_, 'm>, meta: Meta<'m>) -> Result<Builder<'m>> {
1172    #[derive(Serialize)]
1173    struct Params<'a> {
1174        #[serde(flatten)]
1175        shared: Shared<'a>,
1176        module: String,
1177        is_async: bool,
1178        is_test: bool,
1179        is_bench: bool,
1180        deprecated: Option<&'a str>,
1181        #[serde(serialize_with = "serialize_item")]
1182        item: &'a Item,
1183        #[serde(serialize_with = "serialize_component_ref")]
1184        name: ComponentRef<'a>,
1185        args: String,
1186        doc: Option<String>,
1187        return_type: Option<String>,
1188    }
1189
1190    let f = match meta.kind {
1191        Kind::Function(
1192            f @ Function {
1193                signature: Signature::Function,
1194                ..
1195            },
1196        ) => f,
1197        _ => bail!("found meta, but not a function"),
1198    };
1199
1200    let doc = cx.render_docs(meta, meta.docs, true)?;
1201
1202    let return_type = cx.return_type(f.return_type)?;
1203
1204    let name = meta.item.last().context("Missing item name")?;
1205
1206    Ok(Builder::new(cx, move |cx| {
1207        cx.function_template.render(&Params {
1208            shared: cx.shared()?,
1209            module: cx.module_path_html(meta, false)?,
1210            is_async: f.is_async,
1211            is_test: f.is_test,
1212            is_bench: f.is_bench,
1213            deprecated: meta.deprecated,
1214            item: meta.item,
1215            name,
1216            args: cx.args_to_string(f.signature, f.arguments)?,
1217            doc,
1218            return_type,
1219        })
1220    })?)
1221}
1222
1223/// Helper to serialize an item.
1224fn serialize_item<S>(item: &Item, serializer: S) -> Result<S::Ok, S::Error>
1225where
1226    S: Serializer,
1227{
1228    serializer.collect_str(&item.unqalified())
1229}
1230
1231/// Helper to serialize a component ref.
1232fn serialize_component_ref<S>(c: &ComponentRef<'_>, serializer: S) -> Result<S::Ok, S::Error>
1233where
1234    S: Serializer,
1235{
1236    serializer.collect_str(&c)
1237}
1238
1239/// Helper for building an item path.
1240fn build_item_path(
1241    name: &str,
1242    item: &Item,
1243    kind: ItemKind,
1244    path: &mut RelativePathBuf,
1245) -> Result<()> {
1246    if item.is_empty() {
1247        path.push(name);
1248    } else {
1249        for c in item.iter() {
1250            let string = match c {
1251                ComponentRef::Crate(string) => string,
1252                ComponentRef::Str(string) => string,
1253                _ => continue,
1254            };
1255
1256            path.push(string);
1257        }
1258    }
1259
1260    path.set_extension(match kind {
1261        ItemKind::Type => "type.html",
1262        ItemKind::Struct => "struct.html",
1263        ItemKind::Enum => "enum.html",
1264        ItemKind::Module => "module.html",
1265        ItemKind::Macro => "macro.html",
1266        ItemKind::Function => "fn.html",
1267        ItemKind::Trait => "trait.html",
1268    });
1269
1270    Ok(())
1271}
rune/doc/build.rs

rune/doc/
build.rs
