ddoc 0.18.0

doc site generator
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

mod attribute;
mod element;
mod element_key;
mod element_list;
mod menu;
mod nav_link;
mod page_list;
mod text;
mod toc;

pub use {
    attribute::*,
    element::*,
    element_key::*,
    element_list::*,
    menu::*,
    nav_link::*,
    page_list::*,
    text::*,
    toc::*,
};

use {
    crate::{
        before_0_11::NavComponents,
        *,
    },
    indexmap::IndexMap,
    serde::{
        Deserialize,
        Deserializer,
    },
    std::path::Path,
};

pub static CONFIG_FILE_NAME: &str = "ddoc.hjson";

pub type ClassName = String;

#[derive(Debug, Default, Clone, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub struct Config {
    pub title: Option<String>,
    pub description: Option<String>,
    pub ddoc_version: Option<String>,
    #[serde(default, alias = "active-plugins")]
    pub active_plugins: Vec<String>,
    #[serde(default, alias = "pages", alias = "menu")]
    pub site_map: PageList,
    pub favicon: Option<String>,
    /// for compatibility with ddoc (0.11-), this is loaded but only used
    /// through conversion to the new `body` field
    #[serde(flatten)]
    pub old: NavComponents,
    #[serde(
        default = "default_body_element",
        deserialize_with = "deserialize_body_element"
    )]
    pub body: Element,
    #[serde(default)]
    pub vars: IndexMap<String, String>,
}

impl Config {
    /// Read the ddoc.hjson configuration file at the root of a ddoc module
    ///
    /// Return both the config and the path where it was found
    ///
    /// # Errors
    /// Return `DdError::ConfigNotFound` if no ddoc.hjson is found at the specified path
    /// or other `DdError` variants on read/parse errors
    pub fn in_dir(path: &Path) -> DdResult<Option<Sourced<Self>>> {
        let config_path = path.join(CONFIG_FILE_NAME);
        if !config_path.exists() {
            return Ok(None);
        }
        let config: Config = read_file(&config_path)?;
        let config = Sourced::new(config, config_path);
        Ok(Some(config))
    }
    pub fn title(&self) -> &str {
        self.title.as_deref().unwrap_or("Untitled")
    }
    pub fn description(&self) -> Option<&str> {
        self.description.as_deref().filter(|s| !s.is_empty())
    }
    pub fn favicon(&self) -> Option<&str> {
        self.favicon.as_deref().filter(|s| !s.is_empty())
    }
    pub fn var(
        &self,
        name: &str,
    ) -> Option<String> {
        match name {
            "title" => Some(self.title().to_string()),
            "description" => self.description().map(|s| s.to_string()),
            "favicon" => self.favicon().map(|s| s.to_string()),
            _ => self.vars.get(name).cloned(),
        }
    }

    pub fn has_any_plugin(&self) -> bool {
        !self.active_plugins.is_empty()
    }

    /// Add to this main config element the config of a plugin
    pub fn merge(
        &mut self,
        other: &Config,
    ) {
        if self.title.is_none() {
            self.title = other.title.clone();
        }
        if self.description.is_none() {
            self.description = other.description.clone();
        }
        if self.favicon.is_none() {
            self.favicon = other.favicon.clone();
        }
        for (key, value) in &other.vars {
            if !self.vars.contains_key(key) {
                self.vars.insert(key.clone(), value.clone());
            }
        }
        for plugin in &other.active_plugins {
            if !self.active_plugins.contains(plugin) {
                self.active_plugins.push(plugin.clone());
            }
        }
        if !self.body.try_merge(&other.body) {
            warn!(
                "Plugin config body could not be merged into main config body, plugin body will be ignored"
            );
        }
    }
}

fn default_body_element() -> Element {
    Element {
        classes: vec![],
        content: ElementContent::DomTree {
            tag: "body".to_string(),
            children: vec![],
        },
    }
}
fn deserialize_body_element<'de, D: Deserializer<'de>>(
    deserializer: D
) -> Result<Element, D::Error> {
    let element_list = ElementList::deserialize(deserializer)?;
    let element = Element {
        classes: vec![],
        content: ElementContent::DomTree {
            tag: "body".to_string(),
            children: element_list.children,
        },
    };
    Ok(element)
}