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
160
161
162
163
164
165
166
167

use crate::{
    doc_item::DocItem,
    glossary::{generate_module_glossary, ModuleGlossary},
    module::ModuleDocumentation,
};

use super::{error::AutodocsError, generate_module_documentation};

pub const RHAI_ITEM_INDEX_PATTERN: &str = "# rhai-autodocs:index:";
pub const RHAI_IGNORE_PATTERN: &str = "# rhai-autodocs:ignore";

/// Types of markdown processor where the documentation generated will be hosted.
#[derive(Default)]
pub enum MarkdownProcessor {
    /// Generate documentation for mdbook: <https://rust-lang.github.io/mdBook/>
    MdBook,
    /// Generate documentation for docusaurus. <https://docusaurus.io/>
    #[default]
    Docusaurus,
}

#[derive(Default)]
/// Options to configure documentation generation.
pub struct Options {
    pub(crate) items_order: ItemsOrder,
    pub(crate) sections_format: SectionFormat,
    pub(crate) include_standard_packages: bool,
}

/// Create new options used to configure docs generation.
pub fn options() -> Options {
    Options::default()
}

impl Options {
    /// Include the standard package functions and modules documentation
    /// in the generated documentation markdown.
    pub fn include_standard_packages(mut self, include_standard_packages: bool) -> Self {
        self.include_standard_packages = include_standard_packages;

        self
    }

    /// Order documentation items in a specific way.
    /// See [`ItemsOrder`] for more details.
    pub fn order_items_with(mut self, items_order: ItemsOrder) -> Self {
        self.items_order = items_order;

        self
    }

    /// Format doc comments 'sections', markdown that starts with the `#` character,
    /// with special formats.
    /// See [`SectionFormat`] for more details.
    pub fn format_sections_with(mut self, sections_format: SectionFormat) -> Self {
        self.sections_format = sections_format;

        self
    }

    /// Generate documentation based on an engine instance.
    /// Make sure all the functions, operators, plugins, etc. are registered inside this instance.
    ///
    /// # Result
    /// * A vector of documented modules.
    ///
    /// # Errors
    /// * Failed to generate function metadata as json.
    /// * Failed to parse module metadata.
    pub fn generate(self, engine: &rhai::Engine) -> Result<ModuleDocumentation, AutodocsError> {
        generate_module_documentation(engine, &self)
    }

    /// Generate documentation based on an engine instance and a list of all functions signature.
    /// Make sure all the functions, operators, plugins, etc. are registered inside this instance.
    ///
    /// # Result
    /// * A vector of documented modules and the glossary.
    ///
    /// # Errors
    /// * Failed to generate function metadata as json.
    /// * Failed to parse module metadata.
    pub fn generate_with_glossary(
        &self,
        engine: &rhai::Engine,
    ) -> Result<(ModuleDocumentation, ModuleGlossary), AutodocsError> {
        Ok((
            generate_module_documentation(engine, self)?,
            generate_module_glossary(engine, self)?,
        ))
    }
}

/// Select in which order each doc item will be displayed.
#[derive(Default)]
pub enum ItemsOrder {
    /// Display functions by alphabetical order.
    #[default]
    Alphabetical,
    /// Display functions by index using a pre-processing comment with the `# rhai-autodocs:index:<number>` syntax.
    /// The `# rhai-autodocs:index:<number>` line will be removed in the final generated markdown.
    ///
    /// # Example
    ///
    /// ```ignore
    /// /// Function that will appear first in docs.
    /// ///
    /// /// # rhai-autodocs:index:1
    /// #[rhai_fn(global)]
    /// pub fn my_function1() {}
    ///
    /// /// Function that will appear second in docs.
    /// ///
    /// /// # rhai-autodocs:index:2
    /// #[rhai_fn(global)]
    /// pub fn my_function2() {}
    /// ```
    ///
    /// Adding, removing or re-ordering your functions from your api can be a chore
    /// because you have to update all indexes by hand. Thankfully, you will found
    /// a python script in the `scripts` folder of the `rhai-autodocs` repository
    /// that will update the indexes by hand just for you.
    ///
    /// The script generates a .autodocs file from your original source file,
    /// make sure to check that it did not mess with your source code using
    /// a diff tool.
    ByIndex,
}

impl ItemsOrder {
    /// Order [`DocItem`]s following the given option.
    pub(crate) fn order_items(&'_ self, mut items: Vec<DocItem>) -> Vec<DocItem> {
        match self {
            Self::Alphabetical => {
                items.sort_by(|i1, i2| i1.name().cmp(i2.name()));
                items
            }
            Self::ByIndex => {
                items.sort_by_key(DocItem::index);
                items
            }
        }
    }
}

/// Options to format the display of sections marked with the `#`
/// tag in markdown.
#[derive(Default)]
pub enum SectionFormat {
    /// Display sections the same as Rust doc comments, using the
    /// default markdown titles.
    #[default]
    Rust,
    /// Display sections using tabs that wraps all underlying
    /// documentation in them.
    ///
    /// NOTE: [`SectionFormat::fmt_sections`] is called after [`remove_test_code`],
    /// so checking for code blocks and `#` line start is not required because it
    /// was supposed to be removed.
    Tabs,
}

#[derive(Default, Clone, serde::Serialize)]
struct Section {
    pub name: String,
    pub body: String,
}