Improve doc gen

Author: CppCXY

crates/emmylua_doc_cli/src/markdown_generator/global_gen.rs

@@ -0,0 +1,115 @@
+use std::path::Path;
+
+use emmylua_code_analysis::{
+    humanize_type, DbIndex, LuaDecl, LuaDeclId, LuaMemberOwner, LuaPropertyOwnerId, LuaType,
+    RenderLevel,
+};
+use tera::{Context, Tera};
+
+use crate::markdown_generator::{
+    escape_type_name, mod_gen::generate_member_owner_module, IndexStruct,
+};
+
+use super::{render::{render_const_type, render_function_type}, MkdocsIndex};
+
+pub fn generate_global_markdown(
+    db: &DbIndex,
+    tl: &Tera,
+    decl_id: &LuaDeclId,
+    input: &Path,
+    output: &Path,
+    mkdocs_index: &mut MkdocsIndex,
+) -> Option<()> {
+    check_filter(db, decl_id, input)?;
+
+    let mut context = tera::Context::new();
+    let decl = db.get_decl_index().get_decl(decl_id)?;
+    let name = decl.get_name();
+    context.insert("global_name", name);
+
+    let mut template_name = "lua_global_template.tl";
+    match &decl.get_type()? {
+        LuaType::TableConst(table) => {
+            let member_owner = LuaMemberOwner::Element(table.clone());
+            generate_member_owner_module(db, member_owner, name, &mut context)?;
+        }
+        _ => {
+            template_name = "lua_global_template_simple.tl";
+            generate_simple_global(db, decl, &mut context);
+        }
+    }
+
+    let render_text = match tl.render(&template_name, &context) {
+        Ok(text) => text,
+        Err(e) => {
+            eprintln!("Failed to render template: {}", e);
+            return None;
+        }
+    };
+
+    let file_name = format!("{}.md", escape_type_name(&decl.get_name()));
+    mkdocs_index.globals.push(IndexStruct {
+        name: decl.get_name().to_string(),
+        file: format!("globals/{}", file_name.clone()),
+    });
+
+    let outpath = output.join(file_name);
+    println!("output global file: {}", outpath.display());
+    match std::fs::write(outpath, render_text) {
+        Ok(_) => {}
+        Err(e) => {
+            eprintln!("Failed to write file: {}", e);
+            return None;
+        }
+    }
+    Some(())
+}
+
+fn check_filter(db: &DbIndex, decl_id: &LuaDeclId, workspace: &Path) -> Option<()> {
+    let file_id = decl_id.file_id;
+    let file_path = db.get_vfs().get_file_path(&file_id)?;
+    if !file_path.starts_with(workspace) {
+        return None;
+    }
+
+    let decl = db.get_decl_index().get_decl(decl_id)?;
+    let ty = decl.get_type()?;
+    match ty {
+        LuaType::Ref(_) | LuaType::Def(_) => return None,
+        _ => {}
+    }
+
+    Some(())
+}
+
+fn generate_simple_global(db: &DbIndex, decl: &LuaDecl, context: &mut Context) -> Option<()> {
+    let property_owner_id = LuaPropertyOwnerId::LuaDecl(decl.get_id());
+    let property = db.get_property_index().get_property(property_owner_id);
+
+    let description = if let Some(property) = property {
+        *property
+            .description
+            .clone()
+            .unwrap_or("".to_string().into())
+    } else {
+        "".to_string()
+    };
+    context.insert("description", &description);
+
+    let name = decl.get_name();
+    let ty = decl.get_type().unwrap_or(&LuaType::Unknown);
+    if ty.is_function() {
+        let display = render_function_type(db, ty, &name, false);
+        context.insert("display", &display);
+    } else if ty.is_const() {
+        let typ_display = render_const_type(db, &ty);
+        let display = format!("```lua\n{}: {}\n```\n", name, typ_display);
+        context.insert("display", &display);
+    } else {
+        let typ_display = humanize_type(db, &ty, RenderLevel::Detailed);
+        let dispaly = format!("```lua\n{} : {}\n```\n", name, typ_display);
+        context.insert("display", &dispaly);
+    }
+
+    Some(())
+}

crates/emmylua_doc_cli/src/markdown_generator/index_gen.rs

@@ -6,6 +6,7 @@ pub fn generate_index(tl: &Tera, mkdocs: &mut MkdocsIndex, output: &std::path::P
     let mut context = tera::Context::new();
     mkdocs.types.sort_by(|a, b| a.name.cmp(&b.name));
     mkdocs.modules.sort_by(|a, b| a.name.cmp(&b.name));
+    mkdocs.globals.sort_by(|a, b| a.name.cmp(&b.name));
 
 
     if !mkdocs.types.is_empty() {
@@ -14,6 +15,9 @@ pub fn generate_index(tl: &Tera, mkdocs: &mut MkdocsIndex, output: &std::path::P
     if !mkdocs.modules.is_empty() {
         context.insert("modules", &mkdocs.modules);
     }
+    if !mkdocs.globals.is_empty() {
+        context.insert("globals", &mkdocs.globals);
+    }
     let index_path = output.join("docs/index.md");
     let index_text = match tl.render("index_template.tl", &context) {
         Ok(text) => text,

crates/emmylua_doc_cli/src/markdown_generator/mod.rs

@@ -4,6 +4,7 @@ mod mod_gen;
 mod render;
 mod typ_gen;
 mod mixin_copy;
+mod global_gen;
 
 use std::path::PathBuf;
 
@@ -39,6 +40,16 @@ pub fn generate_markdown(
         std::fs::create_dir_all(&module_out).ok()?;
     }
 
+    let global_out = docs_dir.join("globals");
+    if !global_out.exists() {
+        println!("Creating globals directory: {:?}", global_out);
+        std::fs::create_dir_all(&global_out).ok()?;
+    } else {
+        println!("Clearing globals directory: {:?}", global_out);
+        std::fs::remove_dir_all(&global_out).ok()?;
+        std::fs::create_dir_all(&global_out).ok()?;
+    }
+
     let tl = init_tl::init_tl(override_template)?;
     let mut mkdocs_index = MkdocsIndex::default();
     let db = analysis.compilation.get_db();
@@ -54,6 +65,12 @@ pub fn generate_markdown(
         mod_gen::generate_module_markdown(db, &tl, module, &input, &module_out, &mut mkdocs_index);
     }
 
+    let decl_index = db.get_decl_index();
+    let globals = decl_index.get_global_decls();
+    for global_decl_id in globals {
+        global_gen::generate_global_markdown(db, &tl, &global_decl_id, &input, &global_out, &mut mkdocs_index);
+    }
+
     index_gen::generate_index(&tl, &mut mkdocs_index, &output);
 
     if let Some(mixin) = mixin {
@@ -74,6 +91,7 @@ struct MemberDisplay {
 struct MkdocsIndex {
     pub types: Vec<IndexStruct>,
     pub modules: Vec<IndexStruct>,
+    pub globals: Vec<IndexStruct>,
 }
 
 #[derive(Debug, Serialize, Deserialize)]

crates/emmylua_doc_cli/src/markdown_generator/mod_gen.rs

@@ -79,7 +79,7 @@ fn check_filter(db: &DbIndex, file_id: FileId, workspace: &Path) -> Option<()> {
     Some(())
 }
 
-fn generate_member_owner_module(
+pub fn generate_member_owner_module(
     db: &DbIndex,
     member_owner: LuaMemberOwner,
     owner_name: &str,

crates/emmylua_doc_cli/src/markdown_generator/render.rs

@@ -219,6 +219,6 @@ fn render_typ(db: &DbIndex, typ: &LuaType) -> String {
         LuaType::FloatConst(_) => "number".to_string(),
         LuaType::StringConst(_) => "string".to_string(),
         LuaType::BooleanConst(_) => "boolean".to_string(),
-        _ => humanize_type(db, typ, RenderLevel::Detailed),
+        _ => humanize_type(db, typ, RenderLevel::Simple),
     }
 }

crates/emmylua_doc_cli/template/index_template.tl

@@ -11,4 +11,11 @@
 {% for item in modules -%}
 - [{{ item.name }}]({{ item.file }})
 {% endfor %}
+{% endif %}
+
+{% if globals %}
+## Globals
+{% for item in globals -%}
+- [{{ item.name }}]({{ item.file }})
+{% endfor %}
 {% endif %}

crates/emmylua_doc_cli/template/lua_global_template.tl

@@ -0,0 +1,33 @@
+# global {{ global_name }}
+
+{% if description %}
+{{ description }}
+{% endif %}
+---
+{% if methods %}
+## methods
+---
+{% for method in methods %}
+### {{ method.name }}
+---
+{{ method.display }}
+
+{% if method.description %}
+{{ method.description }}
+{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if fields %}
+## fields
+---
+{% for field in fields %}
+### {{ field.name }}
+---
+{{ field.display }}
+
+{% if field.description %}
+{{ field.description }}
+{% endif %}
+{% endfor %}
+{% endif %}

crates/emmylua_doc_cli/template/lua_global_template_simple.tl

@@ -0,0 +1,10 @@
+# global {{ global_name }}
+
+---
+{% if display %}
+{{ display }}
+{% endif %}
+
+{% if description %}
+{{ description }}
+{% endif %}

crates/emmylua_doc_cli/template/mkdocs_template.tl

@@ -35,5 +35,11 @@ nav:
     - {{ item.name }} : {{ item.file }}
     {% endfor %}
   {% endif %}
+  {% if globals %}
+  - Globals:
+    {% for item in globals -%}
+    - {{ item.name }} : {{ item.file }}
+    {% endfor %}
+  {% endif %}
 extra:
   footer: ""