feat: add a script that automatically update function indexing when u…

…sing the `FunctionOrder::ByIndex` option (#7)

* chore: move auto index script to a script folder

* docs: add documentation for the index script

* feat: add help for the index script

* chore: clippy fix

scripts/rhai-autodocs-indexer.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+import sys
+
+if len(sys.argv) != 2:
+    print("""usage: rhai-autodocs-indexer.py <path-to-source-file>
+
+    This script searches for any `# rhai-autodocs:index:` comment and
+    automatically adds the index number following the order of the function
+    in the source file.
+
+    See the `FunctionOrder::ByIndex` option from the rhai-autodocs crate.
+""")
+    exit(1)
+
+file = sys.argv[1]
+
+oldfile = open(file, 'r')
+newfile = open(f"{file}.autodocs", 'w')
+
+function_order = 1
+for line in oldfile:
+    newline = ""
+    if "# rhai-autodocs:index:" in line:
+        newline = f"    /// # rhai-autodocs:index:{function_order}\n"
+        function_order += 1
+    else:
+        newline = line
+
+    newfile.write(newline)

src/options.rs

@@ -101,6 +101,15 @@ pub enum FunctionOrder {
     /// #[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,
 }
 
@@ -130,7 +139,7 @@ impl FunctionOrder {
                         {
                             let index = index
                                 .parse::<usize>()
-                                .map_err(|err| AutodocsError::PreProcessing(format!("failed to parsed order metadata: {}", err.to_string())))?;
+                                .map_err(|err| AutodocsError::PreProcessing(format!("failed to parsed order metadata: {err}")))?;
 
                             if let Some(slot) = ordered.get_mut(index - 1) {
                                 *slot = (function.clone(), polymorphisms.clone());