rune/cli/
doc.rs

Help
1use std::io::Write;
2use std::path::PathBuf;
3
4use crate::doc::Artifacts;
5
6use anyhow::{Context, Result};
7
8use crate::alloc::prelude::*;
9use crate::cli::naming::Naming;
10use crate::cli::{AssetKind, CommandBase, Config, Entry, EntryPoint, ExitCode, Io, SharedFlags};
11use crate::compile::FileSourceLoader;
12use crate::{Diagnostics, Options, Source, Sources};
13
14mod cli {
15    use std::path::PathBuf;
16    use std::vec::Vec;
17
18    use clap::Parser;
19
20    #[derive(Parser, Debug)]
21    #[command(rename_all = "kebab-case")]
22    pub(crate) struct Flags {
23        /// Exit with a non-zero exit-code even for warnings
24        #[arg(long)]
25        pub(super) warnings_are_errors: bool,
26        /// Output directory to write documentation to.
27        #[arg(long)]
28        pub(super) output: Option<PathBuf>,
29        /// Open the generated documentation in a browser.
30        #[arg(long)]
31        pub(super) open: bool,
32        /// Explicit paths to format.
33        pub(super) doc_path: Vec<PathBuf>,
34    }
35}
36
37pub(super) use cli::Flags;
38
39impl CommandBase for Flags {
40    #[inline]
41    fn is_workspace(&self, _: AssetKind) -> bool {
42        true
43    }
44
45    #[inline]
46    fn describe(&self) -> &str {
47        "Documenting"
48    }
49
50    #[inline]
51    fn paths(&self) -> &[PathBuf] {
52        &self.doc_path
53    }
54}
55
56pub(super) fn run<'p, I>(
57    io: &mut Io<'_>,
58    entry: &mut Entry<'_>,
59    c: &Config,
60    flags: &Flags,
61    shared: &SharedFlags,
62    options: &Options,
63    entries: I,
64) -> Result<ExitCode>
65where
66    I: IntoIterator<Item = EntryPoint<'p>>,
67{
68    let root = match &flags.output {
69        Some(root) => root.clone(),
70        None => match &c.manifest_root {
71            Some(path) => path.join("target").join("rune-doc"),
72            None => match std::env::var_os("CARGO_TARGET_DIR") {
73                Some(target) => {
74                    let mut target = PathBuf::from(target);
75                    target.push("rune-doc");
76                    target
77                }
78                None => {
79                    let mut target = PathBuf::new();
80                    target.push("target");
81                    target.push("rune-doc");
82                    target
83                }
84            },
85        },
86    };
87
88    writeln!(io.stdout, "Building documentation: {}", root.display())?;
89
90    let context = shared.context(entry, c, None)?;
91
92    let mut visitors = Vec::new();
93
94    let mut naming = Naming::default();
95
96    for e in entries {
97        let mut options = options.clone();
98
99        if e.is_argument() {
100            options.function_body = true;
101        }
102
103        let item = naming.item(&e)?;
104
105        let mut visitor = crate::doc::Visitor::new(&item)?;
106        let mut sources = Sources::new();
107
108        let source = match Source::from_path(e.path()) {
109            Ok(source) => source,
110            Err(error) => return Err(error).context(e.path().display().try_to_string()?),
111        };
112
113        sources.insert(source)?;
114
115        let mut diagnostics = if shared.warnings || flags.warnings_are_errors {
116            Diagnostics::new()
117        } else {
118            Diagnostics::without_warnings()
119        };
120
121        let mut source_loader = FileSourceLoader::new();
122
123        let _ = crate::prepare(&mut sources)
124            .with_context(&context)
125            .with_diagnostics(&mut diagnostics)
126            .with_options(&options)
127            .with_visitor(&mut visitor)?
128            .with_source_loader(&mut source_loader)
129            .build();
130
131        diagnostics.emit(&mut io.stdout.lock(), &sources)?;
132
133        if diagnostics.has_error() || flags.warnings_are_errors && diagnostics.has_warning() {
134            return Ok(ExitCode::Failure);
135        }
136
137        visitors.try_push(visitor)?;
138    }
139
140    let mut artifacts = Artifacts::new();
141
142    crate::doc::build("root", &mut artifacts, Some(&context), &visitors)?;
143
144    for asset in artifacts.assets() {
145        asset.build(&root)?;
146    }
147
148    if flags.open {
149        let path = root.join("index.html");
150        let _ = webbrowser::open(&path.display().try_to_string()?);
151    }
152
153    Ok(ExitCode::Success)
154}
rune/cli/doc.rs

rune/cli/
doc.rs
