ByoungSooPark/modeling-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Some improvements to the boxed signatures in the docs (#6593)

Browse Source 
* Show a more reasonable name in function docs

Signed-off-by: Nick Cameron <nrc@ncameron.org>

* Fix buggy docs for union types

Signed-off-by: Nick Cameron <nrc@ncameron.org>

* Make types in the docs signatures into links

Signed-off-by: Nick Cameron <nrc@ncameron.org>

---------

Signed-off-by: Nick Cameron <nrc@ncameron.org>
This commit is contained in:
Nick Cameron
2025-05-01 04:03:22 +12:00
committed by GitHub
parent ccd5b0272d
commit c050739f41
128 changed files with 821 additions and 731 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
rust/kcl-lib/src/docs/gen_std_tests.rs
View File

@ -461,7 +461,7 @@ fn generate_type_from_kcl(ty: &TyData, file_name: String, example_name: String)
let data = json!({
"name": ty.qual_name(),
"definition": ty.alias.as_ref().map(|t| format!("type {} = {t}", ty.name)),
"definition": ty.alias.as_ref().map(|t| cleanup_sig(format!("type {} = {t}", ty.preferred_name), ty.referenced_types.iter().filter(|t| !DECLARED_TYPES.contains(&&***t)))),
"summary": ty.summary,
"description": ty.description,
"deprecated": ty.properties.deprecated,
@ -485,8 +485,6 @@ fn generate_function_from_kcl(function: &FnData, file_name: String) -> Result<()
let hbs = init_handlebars()?;
let name = function.name.clone();
let examples: Vec<serde_json::Value> = function
.examples
.iter()
@ -499,7 +497,10 @@ fn generate_function_from_kcl(function: &FnData, file_name: String) -> Result<()
"summary": function.summary,
"description": function.description,
"deprecated": function.properties.deprecated,
"fn_signature": name.clone() + &function.fn_signature(),
"fn_signature": cleanup_sig(function.preferred_name.clone() + &function.fn_signature(), function
.referenced_types
.iter()
.filter(|t| !DECLARED_TYPES.contains(&&***t))),
"tags": [],
"examples": examples,
"is_utilities": false,
@ -624,7 +625,7 @@ fn generate_function(internal_fn: Box<dyn StdLibFn>) -> Result<BTreeMap<String,
"summary": internal_fn.summary(),
"description": internal_fn.description(),
"deprecated": internal_fn.deprecated(),
"fn_signature": internal_fn.fn_signature(true),
"fn_signature": cleanup_sig(internal_fn.fn_signature(true), types.keys()),
"tags": internal_fn.tags(),
"examples": examples,
"is_utilities": internal_fn.tags().contains(&"utilities".to_string()),
@ -653,20 +654,6 @@ fn generate_function(internal_fn: Box<dyn StdLibFn>) -> Result<BTreeMap<String,
Ok(types)
}
fn cleanup_static_links(output: &str) -> String {
let mut cleaned_output = output.to_string();
// Fix the links to the types.
// Gross hack for the stupid alias types.
cleaned_output = cleaned_output.replace("TagNode", "TagDeclarator");
let link = format!("[`{}`](/docs/kcl/types#tag-declaration)", "TagDeclarator");
cleaned_output = cleaned_output.replace("`TagDeclarator`", &link);
let link = format!("[`{}`](/docs/kcl/types#tag-identifier)", "TagIdentifier");
cleaned_output = cleaned_output.replace("`TagIdentifier`", &link);
cleaned_output
}
// Fix the links to the types.
fn cleanup_type_links<'a>(output: &str, types: impl Iterator<Item = &'a String>) -> String {
let mut cleaned_output = output.to_string();
@ -675,11 +662,11 @@ fn cleanup_type_links<'a>(output: &str, types: impl Iterator<Item = &'a String>)
// TODO: This is a hack for the handlebars template being too complex.
cleaned_output = cleaned_output.replace("`[, `number`, `number`]`", "`[number, number]`");
cleaned_output = cleaned_output.replace("`[, `number`, `number`, `number`]`", "`[number, number, number]`");
cleaned_output = cleaned_output.replace("`[, `integer`, `integer`, `integer`]`", "`[integer, integer, integer]`");
// Fix the links to the types.
for type_name in types.map(|s| &**s).chain(DECLARED_TYPES) {
if type_name == "TagDeclarator" || type_name == "TagIdentifier" || type_name == "TagNode" {
if type_name == "TagDeclarator" || type_name == "TagIdentifier" || type_name == "TagNode" || type_name == "tag"
{
continue;
} else {
let link = format!("(/docs/kcl/types/{})", type_name);
@ -694,10 +681,70 @@ fn cleanup_type_links<'a>(output: &str, types: impl Iterator<Item = &'a String>)
// TODO handle union types generically rather than special casing them.
cleaned_output = cleaned_output.replace(
"`Sketch | Plane | Face`",
"[`Sketch`](/docs/kcl/types/Sketch) OR [`Plane`](/docs/kcl/types/Plane) OR [`Face`](/docs/kcl/types/Face)",
"[`Sketch`](/docs/kcl/types/Sketch) or [`Plane`](/docs/kcl/types/Plane) or [`Face`](/docs/kcl/types/Face)",
);
cleaned_output = cleaned_output.replace(
"`Axis3d | Edge`",
"[`Axis3d`](/docs/kcl/types/Axis3d) or [`Edge`](/docs/kcl/types/Edge)",
);
cleaned_output = cleaned_output.replace(
"`Axis2d | Edge`",
"[`Axis2d`](/docs/kcl/types/Axis2d) or [`Edge`](/docs/kcl/types/Edge)",
);
cleanup_static_links(&cleaned_output)
// Fix the links to the types.
// Gross hack for the stupid alias types.
cleaned_output = cleaned_output.replace("TagNode", "TagDeclarator");
let link = "[`TagDeclarator`](/docs/kcl/types#tag-declaration)";
cleaned_output = cleaned_output.replace("`TagDeclarator`", link);
let link = "[`TagIdentifier`](/docs/kcl/types#tag-identifier)";
cleaned_output = cleaned_output.replace("`TagIdentifier`", link);
cleaned_output
}
// TODO total code dup with `cleanup_type_links`, just this version doesn't have the backticks. :-(
fn cleanup_sig<'a>(input: String, types: impl Iterator<Item = &'a String>) -> String {
let mut cleaned_output = input;
// Fix the links to the types.
for type_name in types.map(|s| &**s).chain(DECLARED_TYPES) {
if type_name == "TagDeclarator" || type_name == "TagIdentifier" || type_name == "TagNode" || type_name == "tag"
{
continue;
} else {
let link = format!("(/docs/kcl/types/{})", type_name);
// Do the same for the type with brackets.
cleaned_output = cleaned_output.replace(&format!("[{}]", type_name), &format!("[[{}]]{}", type_name, link));
cleaned_output = cleaned_output.replace(type_name, &format!("[{}]{}", type_name, &link));
}
}
// TODO handle union types generically rather than special casing them.
cleaned_output = cleaned_output.replace(
"Sketch | Plane | Face",
"[Sketch](/docs/kcl/types/Sketch) | [Plane](/docs/kcl/types/Plane) | [Face](/docs/kcl/types/Face)",
);
cleaned_output = cleaned_output.replace(
"Axis3d | Edge",
"[Axis3d](/docs/kcl/types/Axis3d) | [Edge](/docs/kcl/types/Edge)",
);
cleaned_output = cleaned_output.replace(
"Axis2d | Edge",
"[Axis2d](/docs/kcl/types/Axis2d) | [Edge](/docs/kcl/types/Edge)",
);
// Fix the links to the types.
// Gross hack for the stupid alias types.
cleaned_output = cleaned_output.replace("TagNode", "TagDeclarator");
let link = "[TagDeclarator](/docs/kcl/types#tag-declaration)";
cleaned_output = cleaned_output.replace("TagDeclarator", link);
let link = "[TagIdentifier](/docs/kcl/types#tag-identifier)";
cleaned_output = cleaned_output.replace("TagIdentifier", link);
cleaned_output
}
fn add_to_types(