forge_doc/
builder.rs

1use crate::{
2    AsDoc, BufWriter, Document, ParseItem, ParseSource, Parser, Preprocessor,
3    document::DocumentContent, helpers::merge_toml_table, solang_ext::Visitable,
4};
5use alloy_primitives::map::HashMap;
6use eyre::{Context, Result};
7use foundry_compilers::{compilers::solc::SOLC_EXTENSIONS, utils::source_files_iter};
8use foundry_config::{DocConfig, FormatterConfig, filter::expand_globs};
9use itertools::Itertools;
10use mdbook::MDBook;
11use rayon::prelude::*;
12use std::{
13    cmp::Ordering,
14    fs,
15    path::{Path, PathBuf},
16};
17use toml::value;
18
19/// Build Solidity documentation for a project from natspec comments.
20/// The builder parses the source files using [Parser],
21/// then formats and writes the elements as the output.
22#[derive(Debug)]
23pub struct DocBuilder {
24    /// The project root
25    root: PathBuf,
26    /// Path to Solidity source files.
27    sources: PathBuf,
28    /// Paths to external libraries.
29    libraries: Vec<PathBuf>,
30    /// Flag whether to build mdbook.
31    should_build: bool,
32    /// Documentation configuration.
33    config: DocConfig,
34    /// The array of preprocessors to apply.
35    preprocessors: Vec<Box<dyn Preprocessor>>,
36    /// The formatter config.
37    fmt: FormatterConfig,
38    /// Whether to include libraries to the output.
39    include_libraries: bool,
40}
41
42impl DocBuilder {
43    pub(crate) const SRC: &'static str = "src";
44    const SOL_EXT: &'static str = "sol";
45    const README: &'static str = "README.md";
46    const SUMMARY: &'static str = "SUMMARY.md";
47
48    /// Create new instance of builder.
49    pub fn new(
50        root: PathBuf,
51        sources: PathBuf,
52        libraries: Vec<PathBuf>,
53        include_libraries: bool,
54    ) -> Self {
55        Self {
56            root,
57            sources,
58            libraries,
59            include_libraries,
60            should_build: false,
61            config: DocConfig::default(),
62            preprocessors: Default::default(),
63            fmt: Default::default(),
64        }
65    }
66
67    /// Set `should_build` flag on the builder
68    pub fn with_should_build(mut self, should_build: bool) -> Self {
69        self.should_build = should_build;
70        self
71    }
72
73    /// Set config on the builder.
74    pub fn with_config(mut self, config: DocConfig) -> Self {
75        self.config = config;
76        self
77    }
78
79    /// Set formatter config on the builder.
80    pub fn with_fmt(mut self, fmt: FormatterConfig) -> Self {
81        self.fmt = fmt;
82        self
83    }
84
85    /// Set preprocessors on the builder.
86    pub fn with_preprocessor<P: Preprocessor + 'static>(mut self, preprocessor: P) -> Self {
87        self.preprocessors.push(Box::new(preprocessor) as Box<dyn Preprocessor>);
88        self
89    }
90
91    /// Get the output directory
92    pub fn out_dir(&self) -> Result<PathBuf> {
93        Ok(self.root.join(&self.config.out).canonicalize()?)
94    }
95
96    /// Parse the sources and build the documentation.
97    pub fn build(self, compiler: &mut solar::sema::Compiler) -> eyre::Result<()> {
98        fs::create_dir_all(self.root.join(&self.config.out))
99            .wrap_err("failed to create output directory")?;
100
101        // Expand ignore globs
102        let ignored = expand_globs(&self.root, self.config.ignore.iter())?;
103
104        // Collect and parse source files
105        let sources = source_files_iter(&self.sources, SOLC_EXTENSIONS)
106            .filter(|file| !ignored.contains(file))
107            .collect::<Vec<_>>();
108
109        if sources.is_empty() {
110            sh_println!("No sources detected at {}", self.sources.display())?;
111            return Ok(());
112        }
113
114        let library_sources = self
115            .libraries
116            .iter()
117            .flat_map(|lib| source_files_iter(lib, SOLC_EXTENSIONS))
118            .collect::<Vec<_>>();
119
120        let combined_sources = sources
121            .iter()
122            .map(|path| (path, false))
123            .chain(library_sources.iter().map(|path| (path, true)))
124            .collect::<Vec<_>>();
125
126        let out_dir = self.out_dir()?;
127        let documents = compiler.enter_mut(|compiler| -> eyre::Result<Vec<Vec<Document>>> {
128            let gcx = compiler.gcx();
129            let documents = combined_sources
130                .par_iter()
131                .enumerate()
132                .map(|(i, (path, from_library))| {
133                    let path = *path;
134                    let from_library = *from_library;
135                    let mut files = vec![];
136
137                    // Read and parse source file
138                    if let Some((_, ast)) = gcx.get_ast_source(path)
139                        && let Some(source) =
140                            forge_fmt::format_ast(gcx, ast, self.fmt.clone().into())
141                    {
142                        let (mut source_unit, comments) = match solang_parser::parse(&source, i) {
143                            Ok(res) => res,
144                            Err(err) => {
145                                if from_library {
146                                    // Ignore failures for library files
147                                    return Ok(files);
148                                } else {
149                                    return Err(eyre::eyre!(
150                                        "Failed to parse Solidity code for {}\nDebug info: {:?}",
151                                        path.display(),
152                                        err
153                                    ));
154                                }
155                            }
156                        };
157
158                        // Visit the parse tree
159                        let mut doc = Parser::new(comments, source);
160                        source_unit
161                            .visit(&mut doc)
162                            .map_err(|err| eyre::eyre!("Failed to parse source: {err}"))?;
163
164                        // Split the parsed items on top-level constants and rest.
165                        let (items, consts): (Vec<ParseItem>, Vec<ParseItem>) = doc
166                            .items()
167                            .into_iter()
168                            .partition(|item| !matches!(item.source, ParseSource::Variable(_)));
169
170                        // Attempt to group overloaded top-level functions
171                        let mut remaining = Vec::with_capacity(items.len());
172                        let mut funcs: HashMap<String, Vec<ParseItem>> = HashMap::default();
173                        for item in items {
174                            if matches!(item.source, ParseSource::Function(_)) {
175                                funcs.entry(item.source.ident()).or_default().push(item);
176                            } else {
177                                // Put the item back
178                                remaining.push(item);
179                            }
180                        }
181                        let (items, overloaded): (
182                            HashMap<String, Vec<ParseItem>>,
183                            HashMap<String, Vec<ParseItem>>,
184                        ) = funcs.into_iter().partition(|(_, v)| v.len() == 1);
185                        remaining.extend(items.into_iter().flat_map(|(_, v)| v));
186
187                        // Each regular item will be written into its own file.
188                        files = remaining
189                            .into_iter()
190                            .map(|item| {
191                                let relative_path =
192                                    path.strip_prefix(&self.root)?.join(item.filename());
193
194                                let target_path = out_dir.join(Self::SRC).join(relative_path);
195                                let ident = item.source.ident();
196                                Ok(Document::new(
197                                    path.clone(),
198                                    target_path,
199                                    from_library,
200                                    self.config.out.clone(),
201                                )
202                                .with_content(DocumentContent::Single(item), ident))
203                            })
204                            .collect::<eyre::Result<Vec<_>>>()?;
205
206                        // If top-level constants exist, they will be written to the same file.
207                        if !consts.is_empty() {
208                            let filestem = path.file_stem().and_then(|stem| stem.to_str());
209
210                            let filename = {
211                                let mut name = "constants".to_owned();
212                                if let Some(stem) = filestem {
213                                    name.push_str(&format!(".{stem}"));
214                                }
215                                name.push_str(".md");
216                                name
217                            };
218                            let relative_path = path.strip_prefix(&self.root)?.join(filename);
219                            let target_path = out_dir.join(Self::SRC).join(relative_path);
220
221                            let identity = match filestem {
222                                Some(stem) if stem.to_lowercase().contains("constants") => {
223                                    stem.to_owned()
224                                }
225                                Some(stem) => format!("{stem} constants"),
226                                None => "constants".to_owned(),
227                            };
228
229                            files.push(
230                                Document::new(
231                                    path.clone(),
232                                    target_path,
233                                    from_library,
234                                    self.config.out.clone(),
235                                )
236                                .with_content(DocumentContent::Constants(consts), identity),
237                            )
238                        }
239
240                        // If overloaded functions exist, they will be written to the same file
241                        if !overloaded.is_empty() {
242                            for (ident, funcs) in overloaded {
243                                let filename =
244                                    funcs.first().expect("no overloaded functions").filename();
245                                let relative_path = path.strip_prefix(&self.root)?.join(filename);
246
247                                let target_path = out_dir.join(Self::SRC).join(relative_path);
248                                files.push(
249                                    Document::new(
250                                        path.clone(),
251                                        target_path,
252                                        from_library,
253                                        self.config.out.clone(),
254                                    )
255                                    .with_content(
256                                        DocumentContent::OverloadedFunctions(funcs),
257                                        ident,
258                                    ),
259                                );
260                            }
261                        }
262                    };
263
264                    Ok(files)
265                })
266                .collect::<eyre::Result<Vec<_>>>()?;
267
268            Ok(documents)
269        })?;
270
271        // Flatten results and apply preprocessors to files
272        let documents = self
273            .preprocessors
274            .iter()
275            .try_fold(documents.into_iter().flatten().collect_vec(), |docs, p| {
276                p.preprocess(docs)
277            })?;
278
279        // Sort the results and filter libraries.
280        let documents = documents
281            .into_iter()
282            .sorted_by(|doc1, doc2| {
283                doc1.item_path.display().to_string().cmp(&doc2.item_path.display().to_string())
284            })
285            .filter(|d| !d.from_library || self.include_libraries)
286            .collect_vec();
287
288        // Write mdbook related files
289        self.write_mdbook(documents)?;
290
291        // Build the book if requested
292        if self.should_build {
293            MDBook::load(self.out_dir().wrap_err("failed to construct output directory")?)
294                .and_then(|book| book.build())
295                .map_err(|err| eyre::eyre!("failed to build book: {err:?}"))?;
296        }
297
298        Ok(())
299    }
300
301    fn write_mdbook(&self, documents: Vec<Document>) -> eyre::Result<()> {
302        let out_dir = self.out_dir().wrap_err("failed to construct output directory")?;
303        let out_dir_src = out_dir.join(Self::SRC);
304        fs::create_dir_all(&out_dir_src)?;
305
306        // Write readme content if any
307        let homepage_content = {
308            // Default to the homepage README if it's available.
309            // If not, use the src README as a fallback.
310            let homepage_or_src_readme = self
311                .config
312                .homepage
313                .as_ref()
314                .map(|homepage| self.root.join(homepage))
315                .unwrap_or_else(|| self.sources.join(Self::README));
316            // Grab the root readme.
317            let root_readme = self.root.join(Self::README);
318
319            // Check to see if there is a 'homepage' option specified in config.
320            // If not, fall back to src and root readme files, in that order.
321            if homepage_or_src_readme.exists() {
322                fs::read_to_string(homepage_or_src_readme)?
323            } else if root_readme.exists() {
324                fs::read_to_string(root_readme)?
325            } else {
326                String::new()
327            }
328        };
329
330        let readme_path = out_dir_src.join(Self::README);
331        fs::write(readme_path, homepage_content)?;
332
333        // Write summary and section readmes
334        let mut summary = BufWriter::default();
335        summary.write_title("Summary")?;
336        summary.write_link_list_item("Home", Self::README, 0)?;
337        self.write_summary_section(&mut summary, &documents.iter().collect::<Vec<_>>(), None, 0)?;
338        fs::write(out_dir_src.join(Self::SUMMARY), summary.finish())?;
339
340        // Write solidity syntax highlighting
341        fs::write(out_dir.join("solidity.min.js"), include_str!("../static/solidity.min.js"))?;
342
343        // Write css files
344        fs::write(out_dir.join("book.css"), include_str!("../static/book.css"))?;
345
346        // Write book config
347        fs::write(out_dir.join("book.toml"), self.book_config()?)?;
348
349        // Write .gitignore
350        let gitignore = "book/";
351        fs::write(out_dir.join(".gitignore"), gitignore)?;
352
353        // Write doc files
354        for document in documents {
355            fs::create_dir_all(
356                document
357                    .target_path
358                    .parent()
359                    .ok_or_else(|| eyre::format_err!("empty target path; noop"))?,
360            )?;
361            fs::write(&document.target_path, document.as_doc()?)?;
362        }
363
364        Ok(())
365    }
366
367    fn book_config(&self) -> eyre::Result<String> {
368        // Read the default book first
369        let mut book: value::Table = toml::from_str(include_str!("../static/book.toml"))?;
370        book["book"]
371            .as_table_mut()
372            .unwrap()
373            .insert(String::from("title"), self.config.title.clone().into());
374        if let Some(ref repo) = self.config.repository {
375            // Create the full repository URL.
376            let git_repo_url = if let Some(path) = &self.config.path {
377                // If path is specified, append it to the repository URL.
378                format!("{}/{}", repo.trim_end_matches('/'), path.trim_start_matches('/'))
379            } else {
380                // If no path specified, use repository URL as-is.
381                repo.clone()
382            };
383
384            book["output"].as_table_mut().unwrap()["html"]
385                .as_table_mut()
386                .unwrap()
387                .insert(String::from("git-repository-url"), git_repo_url.into());
388        }
389
390        // Attempt to find the user provided book path
391        let book_path = {
392            if self.config.book.is_file() {
393                Some(self.config.book.clone())
394            } else {
395                let book_path = self.config.book.join("book.toml");
396                if book_path.is_file() { Some(book_path) } else { None }
397            }
398        };
399
400        // Merge two book configs
401        if let Some(book_path) = book_path {
402            merge_toml_table(&mut book, toml::from_str(&fs::read_to_string(book_path)?)?);
403        }
404
405        Ok(toml::to_string_pretty(&book)?)
406    }
407
408    fn write_summary_section(
409        &self,
410        summary: &mut BufWriter,
411        files: &[&Document],
412        base_path: Option<&Path>,
413        depth: usize,
414    ) -> eyre::Result<()> {
415        if files.is_empty() {
416            return Ok(());
417        }
418
419        if let Some(path) = base_path {
420            let title = path.iter().next_back().unwrap().to_string_lossy();
421            if depth == 1 {
422                summary.write_title(&title)?;
423            } else {
424                let summary_path = path.join(Self::README);
425                summary.write_link_list_item(
426                    &format!("❱ {title}"),
427                    &summary_path.display().to_string(),
428                    depth - 1,
429                )?;
430            }
431        }
432
433        // Group entries by path depth
434        let mut grouped = HashMap::new();
435        for file in files {
436            let path = file.item_path.strip_prefix(&self.root)?;
437            let key = path.iter().take(depth + 1).collect::<PathBuf>();
438            grouped.entry(key).or_insert_with(Vec::new).push(*file);
439        }
440        // Sort entries by path depth
441        let grouped = grouped.into_iter().sorted_by(|(lhs, _), (rhs, _)| {
442            let lhs_at_end = lhs.extension().map(|ext| ext == Self::SOL_EXT).unwrap_or_default();
443            let rhs_at_end = rhs.extension().map(|ext| ext == Self::SOL_EXT).unwrap_or_default();
444            if lhs_at_end == rhs_at_end {
445                lhs.cmp(rhs)
446            } else if lhs_at_end {
447                Ordering::Greater
448            } else {
449                Ordering::Less
450            }
451        });
452
453        let out_dir = self.out_dir().wrap_err("failed to construct output directory")?;
454        let mut readme = BufWriter::new("\n\n# Contents\n");
455        for (path, files) in grouped {
456            if path.extension().map(|ext| ext == Self::SOL_EXT).unwrap_or_default() {
457                for file in files {
458                    let ident = &file.identity;
459
460                    let summary_path = &file.target_path.strip_prefix(out_dir.join(Self::SRC))?;
461                    summary.write_link_list_item(
462                        ident,
463                        &summary_path.display().to_string(),
464                        depth,
465                    )?;
466
467                    let readme_path = base_path
468                        .map(|path| summary_path.strip_prefix(path))
469                        .transpose()?
470                        .unwrap_or(summary_path);
471                    readme.write_link_list_item(ident, &readme_path.display().to_string(), 0)?;
472                }
473            } else {
474                let name = path.iter().next_back().unwrap().to_string_lossy();
475                let readme_path = Path::new("/").join(&path).display().to_string();
476                readme.write_link_list_item(&name, &readme_path, 0)?;
477                self.write_summary_section(summary, &files, Some(&path), depth + 1)?;
478            }
479        }
480        if !readme.is_empty()
481            && let Some(path) = base_path
482        {
483            let path = out_dir.join(Self::SRC).join(path);
484            fs::create_dir_all(&path)?;
485            fs::write(path.join(Self::README), readme.finish())?;
486        }
487        Ok(())
488    }
489}
forge_doc/builder.rs

forge_doc/
builder.rs
