refactor(docs): autogenerate framework docs

crates/iota-framework/Cargo.toml

@@ -28,3 +28,5 @@ iota-move-build.workspace = true
 move-binary-format.workspace = true
 move-compiler.workspace = true
 move-package.workspace = true
+
+capitalize = "0.3.4"

crates/iota-framework/build.rs

@@ -5,16 +5,18 @@
 use std::{
     collections::BTreeMap,
     env, fs,
+    io::Write,
     path::{Path, PathBuf},
 };
 
 use anyhow::Result;
+use capitalize::Capitalize;
 use iota_move_build::{BuildConfig, IotaPackageHooks};
 use move_binary_format::CompiledModule;
 use move_compiler::editions::Edition;
 use move_package::{BuildConfig as MoveBuildConfig, LintFlag};
 
-const DOCS_DIR: &str = "docs";
+const DOCS_DIR: &str = "../../docs/content/references/framework/";
 
 /// Save revision info to environment variable
 fn main() {
@@ -196,21 +198,26 @@ fn build_packages_with_move_config(
             std::fs::remove_dir_all(DOCS_DIR).unwrap();
         }
         let mut files_to_write = BTreeMap::new();
+        /*create_category_file(deepbook_dir);
         relocate_docs(
             deepbook_dir,
             &deepbook_pkg.package.compiled_docs.unwrap(),
             &mut files_to_write,
-        );
+        );*/
+        create_category_file(system_dir);
         relocate_docs(
             system_dir,
             &system_pkg.package.compiled_docs.unwrap(),
             &mut files_to_write,
         );
+        create_category_file(framework_dir);
+        create_category_file(stdlib_dir);
         relocate_docs(
             framework_dir,
             &framework_pkg.package.compiled_docs.unwrap(),
             &mut files_to_write,
         );
+        create_category_file(stardust_dir);
         relocate_docs(
             stardust_dir,
             &stardust_pkg.package.compiled_docs.unwrap(),
@@ -219,12 +226,20 @@ fn build_packages_with_move_config(
         for (fname, doc) in files_to_write {
             let mut dst_path = PathBuf::from(DOCS_DIR);
             dst_path.push(fname);
-            fs::create_dir_all(dst_path.parent().unwrap()).unwrap();
             fs::write(dst_path, doc).unwrap();
         }
     }
 }
 
+/// Create a Docusaurus category file for the specified prefix.
+fn create_category_file(prefix: &str) {
+    let mut path = PathBuf::from(DOCS_DIR).join(prefix);
+    fs::create_dir_all(path.clone()).unwrap();
+    path.push("_category_.json");
+    let mut file = fs::File::create(path).unwrap();
+    write!(file, "{{\"label\":\"{}\",\"link\":{{\"type\":\"generated-index\",\"slug\":\"/references/framework/{}\",\"description\":\"Documentation for the modules in the iota/crates/iota-framework/packages/{} crate. Select a module from the list to see its details.\"}}}}", prefix.split('-').map(|w| w.capitalize()).collect::<Vec<String>>().join(" "), prefix, prefix).unwrap();
+}
+
 /// Post process the generated docs so that they are in a format that can be
 /// consumed by docusaurus.
 /// * Flatten out the tree-like structure of the docs directory that we generate
@@ -253,6 +268,7 @@ fn relocate_docs(prefix: &str, files: &[(String, String)], output: &mut BTreeMap
     let link_to_regex = regex::Regex::new(r#"<a href="(\S*)">([\s\S]*?)</a>"#).unwrap();
     let code_regex = regex::Regex::new(r"<code>([\s\S]*?)<\/code>").unwrap();
     let type_regex = regex::Regex::new(r"(\S*?)<(IOTA|SMR|0xabcded::soon::SOON|T)>").unwrap();
+    let none_pre_code_regex = regex::Regex::new(r"([^>])<code>([\s\S]*?)</code>").unwrap();
 
     for (file_name, file_content) in files {
         let path = PathBuf::from(file_name);
@@ -292,13 +308,17 @@ fn relocate_docs(prefix: &str, files: &[(String, String)], output: &mut BTreeMap
             // Here we remove the extension from `to` property in Link tags
             .replace(".md", "");
 
+        // Remove <code> tags that are not in between <pre> tags
+        let content = none_pre_code_regex.replace_all(&content, r#"$1$2"#);
+
         // Store all files in a map to deduplicate and change extension to mdx
         output.entry(format!("{}x", file_name)).or_insert_with(|| {
             title_regex.replace_all(&content, |caps: &regex::Captures| {
                     let title_type = caps.get(1).unwrap().as_str();
                     let name = caps.get(2).unwrap().as_str();
                     let anchor = name.replace("::", "_");
-                    format!("---\ntitle: {}`{}`\n---\nimport Link from '@docusaurus/Link';\n\n<Link id=\"{}\"/>", title_type, name, anchor)
+                    // Remove backticks from title and add module name as sidebar label
+                    format!("---\ntitle: {}{}\nsidebar_label: {}\n---\nimport Link from '@docusaurus/Link';\n\n<Link id=\"{}\"/>", title_type, name, name.split("::").last().unwrap(), anchor)
         }).to_string()
         });
     }

crates/iota-framework/docs/deepbook/_category_.json

@@ -0,0 +1 @@
+{"label":"Deepbook","link":{"type":"generated-index","slug":"/references/framework/deepbook","description":"Documentation for the modules in the iota/crates/iota-framework/packages/deepbook crate. Select a module from the list to see its details."}}