rhai_autodocs/
export.rs

1use crate::{
2    item::Item,
3    module::{generate_module_documentation, Documentation, Error},
4};
5
6pub(crate) const RHAI_ITEM_INDEX_PATTERN: &str = "# rhai-autodocs:index:";
7
8#[derive(Default)]
9/// Options to configure documentation generation.
10pub struct Options {
11    pub(crate) items_order: ItemsOrder,
12    pub(crate) sections_format: SectionFormat,
13    pub(crate) include_standard_packages: bool,
14}
15
16impl Options {
17    /// Include the standard package functions and modules documentation
18    /// in the generated documentation markdown.
19    #[must_use]
20    pub const fn include_standard_packages(mut self, include_standard_packages: bool) -> Self {
21        self.include_standard_packages = include_standard_packages;
22
23        self
24    }
25
26    /// Order documentation items in a specific way.
27    /// See [`ItemsOrder`] for more details.
28    #[must_use]
29    pub const fn order_items_with(mut self, items_order: ItemsOrder) -> Self {
30        self.items_order = items_order;
31
32        self
33    }
34
35    /// Format doc comments 'sections', markdown that starts with the `#` character,
36    /// with special formats.
37    /// See [`SectionFormat`] for more details.
38    #[must_use]
39    pub const fn format_sections_with(mut self, sections_format: SectionFormat) -> Self {
40        self.sections_format = sections_format;
41
42        self
43    }
44
45    /// Generate documentation based on an engine instance.
46    /// Make sure all the functions, operators, plugins, etc. are registered inside this instance.
47    ///
48    /// # Result
49    /// * A vector of documented modules.
50    ///
51    /// # Errors
52    /// * Failed to generate function metadata as json.
53    /// * Failed to parse module metadata.
54    pub fn export(self, engine: &rhai::Engine) -> Result<Documentation, Error> {
55        generate_module_documentation(engine, &self)
56    }
57}
58
59/// Select in which order each doc item will be displayed.
60#[derive(Default)]
61pub enum ItemsOrder {
62    /// Display functions by alphabetical order.
63    #[default]
64    Alphabetical,
65    /// Display functions by index using a pre-processing comment with the `# rhai-autodocs:index:<number>` syntax.
66    /// The `# rhai-autodocs:index:<number>` line will be removed in the final generated markdown.
67    ///
68    /// # Example
69    ///
70    /// ```ignore
71    /// /// Function that will appear first in docs.
72    /// ///
73    /// /// # rhai-autodocs:index:1
74    /// #[rhai_fn(global)]
75    /// pub fn my_function1() {}
76    ///
77    /// /// Function that will appear second in docs.
78    /// ///
79    /// /// # rhai-autodocs:index:2
80    /// #[rhai_fn(global)]
81    /// pub fn my_function2() {}
82    /// ```
83    ///
84    /// Adding, removing or re-ordering your functions from your api can be a chore
85    /// because you have to update all indexes by hand. Thankfully, you will found
86    /// a python script in the `scripts` folder of the `rhai-autodocs` repository
87    /// that will update the indexes by hand just for you.
88    ///
89    /// The script generates a .autodocs file from your original source file,
90    /// make sure to check that it did not mess with your source code using
91    /// a diff tool.
92    ByIndex,
93}
94
95impl ItemsOrder {
96    /// Order [`DocItem`]s following the given option.
97    pub(crate) fn order_items(&'_ self, mut items: Vec<Item>) -> Vec<Item> {
98        match self {
99            Self::Alphabetical => {
100                items.sort_by(|i1, i2| i1.name().cmp(i2.name()));
101                items
102            }
103            Self::ByIndex => {
104                items.sort_by_key(Item::index);
105                items
106            }
107        }
108    }
109}
110
111/// Options to format the display of sections marked with the `#`
112/// tag in markdown.
113#[derive(Default)]
114pub enum SectionFormat {
115    /// Display sections the same as Rust doc comments, using the
116    /// default markdown titles.
117    #[default]
118    Rust,
119    /// Display sections using tabs that wraps all underlying
120    /// documentation in them.
121    Tabs,
122}
123
124/// Create new options used to configure docs generation.
125#[must_use]
126pub fn options() -> Options {
127    Options::default()
128}
rhai_autodocs/export.rs

rhai_autodocs/
export.rs
