allow the user to use globs in the list of extra files

and only issue a warning if any of them cannot be read, so that the
rest of the documentation is still generated.

Author: db48x

CONFIG.md

@@ -1,5 +1,5 @@
 # Configuration options
-The configuration file is a TOML file with the following sections:
+The configuration file is a TOML file named `config.toml` with the following sections:
 
 ## `project`
 - `name`: Project name.
@@ -9,7 +9,6 @@ The configuration file is a TOML file with the following sections:
 - `glob`: Glob to use for finding documented files.
 - `compiler_arguments`: List of arguments to pass to libclang while parsing code.
 
-
 ## `output`
 - `static_dir`: Path to a directory containing static files that will be copied in the output directory, this is where `style.css` will typically be located.
 - `path`: Path to the output directory.
@@ -18,7 +17,7 @@ The configuration file is a TOML file with the following sections:
 
 ## `pages`
 - `index` (optional): Markdown file to use as the index file, if an index page is not specified, the root namespace's comment will be used instead.
-- `extra` (optional): List of file paths to serve as extra documentation pages.
+- `extra` (optional): List of file paths to serve as extra documentation pages. These may be globs.
 
 ## `doctests` (optional)
 - `enable`: Whether to enable documentation tests or not.
@@ -51,4 +50,3 @@ enable = false
 run = true
 compiler_invocation = ["clang++", "{file}", "-o", "{out}", "-Iinclude", "-std=c++20"]
 ```
-

src/main.rs

@@ -3,7 +3,7 @@ use glob::glob;
 use indicatif::{ProgressBar, ProgressStyle};
 use render::get_path_for_name;
 use serde::Serialize;
-use std::time::Duration;
+use std::{path::Path, time::Duration};
 
 mod comment;
 mod config;
@@ -13,7 +13,7 @@ mod render;
 mod report;
 mod templates;
 
-use report::report_error;
+use report::{report_error, report_warning};
 
 #[derive(Parser, Debug)]
 struct Cli {
@@ -75,17 +75,17 @@ fn main() {
             let bar = ProgressBar::new_spinner();
 
             for file in glob(&config.input.glob).expect("Failed to read glob pattern") {
-                let file = match file {
-                    Ok(file) => file,
+                match file {
+                    Ok(file) => {
+                        bar.set_message(format!("Parsing {}", file.to_str().unwrap()));
+                        parser.parse(&config, file.to_str().unwrap(), &mut output);
+                        bar.tick();
+                    },
                     Err(e) => {
-                        report_error(&format!("Error reading file: {}", e));
-                        std::process::exit(1);
+                        report_warning(&format!("Error reading input file: {e:}"));
                     }
                 };
 
-                bar.set_message(format!("Parsing {}", file.to_str().unwrap()));
-                parser.parse(&config, file.to_str().unwrap(), &mut output);
-                bar.tick();
             }
 
             bar.finish_and_clear();
@@ -125,25 +125,30 @@ fn main() {
 
             let mut extra_pages = Vec::new();
 
-            for page_path in config.pages.extra.clone().unwrap_or_default() {
-                let page_source = match std::fs::read_to_string(&page_path) {
-                    Ok(source) => source,
-                    Err(e) => {
-                        report_error(&format!("Error reading file: {}", e));
-                        std::process::exit(1);
-                    }
-                };
-
-                let mut page =
-                    render::process_markdown(&page_source, &output.index, &mut doctests, &config);
-
-                if page.title.is_empty() {
-                    page.title = page_path.split("/").last().unwrap().to_string();
+            for g in &config.pages.extra.clone().unwrap_or_default() {
+                for file in glob(g).expect("Failed to read glob pattern") {
+                    match file {
+                        Ok(page_path) => {
+                            match std::fs::read_to_string(&page_path) {
+                                Ok(source) => {
+                                    let mut page =
+                                        render::process_markdown(&source, &output.index, &mut doctests, &config);
+                                    if page.title.is_empty() {
+                                        page.title = page_path.file_name().unwrap().to_string_lossy().into_owned();
+                                    }
+                                    page.path = page_path;
+                                    extra_pages.push(page);
+                                },
+                                Err(e) => {
+                                    report_warning(&format!("Error reading extra file “{page_path:?}”: {e}"));
+                                }
+                            };
+                        },
+                        Err(e) => {
+                            report_warning(&format!("Error reading extra file “{g}”: {e}"));
+                        }
+                    };
                 }
-
-                page.path = page_path.to_string();
-
-                extra_pages.push(page);
             }
 
             let pages = Pages {
@@ -192,13 +197,8 @@ fn main() {
                 .unwrap();
 
             for page in &pages.extra {
-                let path = page.path.split("/").collect::<Vec<&str>>();
-                std::fs::create_dir_all(format!(
-                    "{}/{}",
-                    config.output.path,
-                    path[..path.len() - 1].join("/")
-                ))
-                .map_err(|e| {
+                let path = Path::new(&config.output.path).join(page.path.parent().unwrap_or_else(|| &Path::new("")));
+                std::fs::create_dir_all(path).map_err(|e| {
                     report_error(&format!("Error creating output directory: {}", e));
                     std::process::exit(1);
                 })
@@ -217,7 +217,7 @@ fn main() {
                 context.insert("title", &page.title);
 
                 std::fs::write(
-                    format!("{}/{}.html", config.output.path, page.path),
+                    format!("{}/{}.html", config.output.path, page.path.display()),
                     tera.render("docpage", &context).unwrap(),
                 )
                 .map_err(|e| {
@@ -284,7 +284,7 @@ fn main() {
                 index.push(SearchIndex {
                     id,
                     name: page.title.clone(),
-                    link: page.path.clone(),
+                    link: page.path.to_string_lossy().into_owned(),
                     kind: "page".to_string(),
                 });
 

src/render.rs

@@ -5,6 +5,7 @@ use crate::report::report_warning;
 
 use serde::Serialize;
 use std::collections::HashMap;
+use std::path::PathBuf;
 
 use pulldown_cmark::{CodeBlockKind, Event, Tag, TagEnd};
 use pygmentize::HtmlFormatter;
@@ -13,7 +14,7 @@ use pygmentize::HtmlFormatter;
 pub struct Page {
     pub title: String,
     pub content: String,
-    pub path: String,
+    pub path: PathBuf,
 }
 
 pub fn get_path_for_name(name: &str, index: &HashMap<String, String>) -> Option<String> {
@@ -177,7 +178,7 @@ pub fn process_markdown(
     Page {
         content: html_output,
         title,
-        path: "".to_string(),
+        path: PathBuf::new()
     }
 }
 

src/report.rs

@@ -2,3 +2,7 @@ pub fn report_error(error: &str) {
     eprintln!("\x1b[1;31mError\x1b[0m: {}", error);
     std::process::exit(1);
 }
+
+pub fn report_warning(error: &str) {
+    eprintln!("\x1b[1;33mWarning\x1b[0m: {}", error);
+}