Docs improvements (#6615)

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

rust/kcl-lib/src/docs/kcl_doc.rs

@@ -1,8 +1,4 @@
-use std::{
-    collections::{HashMap, HashSet},
-    fmt,
-    str::FromStr,
-};
+use std::{collections::HashMap, fmt, str::FromStr};
 
 use regex::Regex;
 use tower_lsp::lsp_types::{
@@ -13,7 +9,7 @@ use tower_lsp::lsp_types::{
 use crate::{
     execution::annotations,
     parsing::{
-        ast::types::{Annotation, ImportSelector, ItemVisibility, Node, PrimitiveType, Type, VariableKind},
+        ast::types::{Annotation, ImportSelector, ItemVisibility, Node, VariableKind},
         token::NumericSuffix,
     },
     ModuleId,
@@ -159,6 +155,15 @@ impl DocData {
         }
     }
 
+    #[allow(dead_code)]
+    pub fn preferred_name(&self) -> &str {
+        match self {
+            DocData::Fn(f) => &f.preferred_name,
+            DocData::Const(c) => &c.preferred_name,
+            DocData::Ty(t) => &t.preferred_name,
+        }
+    }
+
     pub fn qual_name(&self) -> &str {
         match self {
             DocData::Fn(f) => &f.qual_name,
@@ -180,18 +185,18 @@ impl DocData {
     #[allow(dead_code)]
     pub fn file_name(&self) -> String {
         match self {
-            DocData::Fn(f) => f.qual_name.replace("::", "-"),
+            DocData::Fn(f) => format!("functions/{}", f.qual_name.replace("::", "-")),
             DocData::Const(c) => format!("consts/{}", c.qual_name.replace("::", "-")),
-            DocData::Ty(t) => format!("types/{}", t.name.clone()),
+            DocData::Ty(t) => format!("types/{}", t.qual_name.replace("::", "-")),
         }
     }
 
     #[allow(dead_code)]
     pub fn example_name(&self) -> String {
         match self {
-            DocData::Fn(f) => f.qual_name.replace("::", "-"),
+            DocData::Fn(f) => format!("fn_{}", f.qual_name.replace("::", "-")),
             DocData::Const(c) => format!("const_{}", c.qual_name.replace("::", "-")),
-            DocData::Ty(t) => t.name.clone(),
+            DocData::Ty(t) => format!("ty_{}", t.qual_name.replace("::", "-")),
         }
     }
 
@@ -400,8 +405,6 @@ pub struct FnData {
     /// Code examples.
     /// These are tested and we know they compile and execute.
     pub examples: Vec<(String, ExampleProperties)>,
-    #[allow(dead_code)]
-    pub referenced_types: Vec<String>,
 
     pub module_name: String,
 }
@@ -420,16 +423,6 @@ impl FnData {
         let name = var.declaration.id.name.clone();
         qual_name.push_str(&name);
 
-        let mut referenced_types = HashSet::new();
-        if let Some(t) = &expr.return_type {
-            collect_type_names(&mut referenced_types, t);
-        }
-        for p in &expr.params {
-            if let Some(t) = &p.type_ {
-                collect_type_names(&mut referenced_types, t);
-            }
-        }
-
         FnData {
             preferred_name: format!("{preferred_prefix}{name}"),
             name,
@@ -445,7 +438,6 @@ impl FnData {
             summary: None,
             description: None,
             examples: Vec::new(),
-            referenced_types: referenced_types.into_iter().collect(),
             module_name: module_name.to_owned(),
         }
     }
@@ -726,8 +718,6 @@ pub struct TyData {
     /// Code examples.
     /// These are tested and we know they compile and execute.
     pub examples: Vec<(String, ExampleProperties)>,
-    #[allow(dead_code)]
-    pub referenced_types: Vec<String>,
 
     pub module_name: String,
 }
@@ -741,10 +731,6 @@ impl TyData {
     ) -> Self {
         let name = ty.name.name.clone();
         qual_name.push_str(&name);
-        let mut referenced_types = HashSet::new();
-        if let Some(t) = &ty.alias {
-            collect_type_names(&mut referenced_types, t);
-        }
 
         TyData {
             preferred_name: format!("{preferred_prefix}{name}"),
@@ -760,7 +746,6 @@ impl TyData {
             summary: None,
             description: None,
             examples: Vec::new(),
-            referenced_types: referenced_types.into_iter().collect(),
             module_name: module_name.to_owned(),
         }
     }
@@ -1056,35 +1041,6 @@ impl ApplyMeta for ArgData {
     }
 }
 
-fn collect_type_names(acc: &mut HashSet<String>, ty: &Type) {
-    match ty {
-        Type::Primitive(primitive_type) => {
-            acc.insert(collect_type_names_from_primitive(primitive_type));
-        }
-        Type::Array { ty, .. } => {
-            collect_type_names(acc, ty);
-        }
-        Type::Union { tys } => tys.iter().for_each(|t| {
-            acc.insert(collect_type_names_from_primitive(t));
-        }),
-        Type::Object { properties } => properties.iter().for_each(|p| {
-            if let Some(t) = &p.type_ {
-                collect_type_names(acc, t)
-            }
-        }),
-    }
-}
-
-fn collect_type_names_from_primitive(ty: &PrimitiveType) -> String {
-    match ty {
-        PrimitiveType::String => "string".to_owned(),
-        PrimitiveType::Number(_) => "number".to_owned(),
-        PrimitiveType::Boolean => "bool".to_owned(),
-        PrimitiveType::Tag => "tag".to_owned(),
-        PrimitiveType::Named(id) => id.name.clone(),
-    }
-}
-
 #[cfg(test)]
 mod test {
     use kcl_derive_docs::for_each_std_mod;

rust/kcl-lib/src/docs/templates/array.hbs

@@ -1 +0,0 @@
-{{~ #if maxItems ~}}{{~ #if (lte maxItems 3) ~}}`[{{#times maxItems ~}}{{~ #if @first ~}}{{else ~}}, {{/if ~}}{{> propertyType ../items}}{{/times}}]`{{else ~}}`[` {{ > propertyType items }} `]`{{~ /if ~}}{{else ~}}`[` {{ > propertyType items }} `]`{{~ /if ~}}

rust/kcl-lib/src/docs/templates/consts-index.hbs

@@ -1,17 +0,0 @@
----
-title: "KCL Constants"
-excerpt: "Documentation for the KCL constants."
-layout: manual
----
-
-## Table of Contents
-
-{{#each consts}}
-
-### `{{name}}`
-
-{{#each consts}}
-- [`{{name}}`](/docs/kcl/{{file_name}})
-{{/each}}
-{{/each}}
-

rust/kcl-lib/src/docs/templates/index.hbs

@@ -12,11 +12,31 @@ layout: manual
 * [`{{name}}`](kcl/{{file_name}})
 {{/each}}
 
-### Standard library
+### Functions
 
-{{#each modules}}
-* **{{name}}**
 {{#each functions}}
+* **{{name}}**
+{{#each items}}
   * [`{{name}}`](kcl/{{file_name}})
 {{/each}}
 {{/each}}
+
+### Constants
+
+{{#each consts}}
+* **{{name}}**
+{{#each items}}
+  * [`{{name}}`](kcl/{{file_name}})
+{{/each}}
+{{/each}}
+
+### Types
+
+See also the [types overview](types)
+
+{{#each types}}
+* **{{name}}**
+{{#each items}}
+  * [`{{name}}`](kcl/{{file_name}})
+{{/each}}
+{{/each}}

rust/kcl-lib/src/docs/templates/properties.hbs

@@ -1,13 +0,0 @@
-{{#if properties}}
-{{#if @root.inDefinition}}
-#### Properties
-{{else}}
-## Properties
-{{/if}}
-
-| Property | Type | Description | Required |
-|----------|------|-------------|----------|
-{{#each properties}}
-| `{{@key}}` | {{~ > propertyType this ~}} | {{{firstLine this.description}}} | {{#if (lookup ../required @key)}}Yes{{else}}No{{/if}} |
-{{/each}}
-{{/if}}

rust/kcl-lib/src/docs/templates/propertyType.hbs

@@ -1,11 +0,0 @@
-{{~ #if $ref ~}}
-{{pretty_ref $ref}}{{else if anyOf ~}}
-**anyOf:** {{#each anyOf}}{{> propertyType this}}{{#unless @last}} **OR** {{/unless}}{{/each}}{{else if oneOf ~}}
-**oneOf:** {{#each oneOf}}{{> propertyType this}}{{#unless @last}} **OR** {{/unless}}{{/each}}{{else if allOf ~}}
-**allOf:** {{#each allOf}}{{> propertyType this}}{{#unless @last}} **OR** {{/unless}}{{/each}}{{else if enum ~}}
-enum: {{pretty_enum enum}}{{else if items ~}}
-{{~ >array ~}}{{else ~}}
-`{{type}}{{~ #if format }}{{#if neq format "double" }} ({{format}}){{~/if ~}}
-{{~ /if ~}}`
-{{~ #if maximum }} (**maximum:** {{maximum}}){{~/if~}}{{~ #if minimum }} (**minimum:** {{minimum}}){{~/if~}}
-{{~ /if ~}}

rust/kcl-lib/src/docs/templates/schema.hbs

@@ -1,70 +0,0 @@
-{{#if description}}
-{{{description}}}
-{{/if}}
-
-{{#if $ref}}
-{{pretty_ref $ref}}
-{{else if enum}}
-**enum:** {{pretty_enum enum}}
-{{else if type}}
-**Type:** `{{type}}`{{~ #if format }} (`{{format}}`){{~/if ~}}{{~ #if maximum }} (**maximum:** {{maximum}}){{~/if~}}{{~ #if minimum }} (**minimum:** {{minimum}}){{~/if~}}
-{{else}}
-{{/if}}
-
-{{#if $schema}}
-**Schema:** `{{$schema}}`
-{{/if}}
-
-{{#if items}}
-{{>array}}
-{{/if}}
-
-{{#if anyOf}}
-**This schema accepts any of the following:**
-
-{{#each anyOf}}
-{{> schema this}}
-----
-{{/each}}
-{{/if}}
-
-{{#if oneOf}}
-**This schema accepts exactly one of the following:**
-
-{{#each oneOf}}
-{{> schema this}}
-----
-{{/each}}
-{{/if}}
-
-{{#if allOf}}
-**This schema requires all of the following:**
-
-{{#each allOf}}
-{{> schema this}}
-----
-{{/each}}
-{{/if}}
-
-{{> properties}}
-
-{{#if definitions}}
-## Definitions
-
-{{#each definitions}}
-### {{@key}}
-
-{{> schemaType this}}
-
-{{/each}}
-{{/if}}
-
-{{#if examples}}
-## Examples
-
-{{#each examples}}
-```json
-{{{json this}}}
-```
-{{/each}}
-{{/if}}

rust/kcl-lib/src/docs/templates/schemaType.hbs

@@ -1,19 +0,0 @@
-{{#if $ref}}
-{{pretty_ref $ref}}
-{{else if anyOf}}
-**anyOf**
-{{else if oneOf}}
-**oneOf**
-{{else if allOf}}
-**allOf**
-{{else if enum}}
-**enum:** {{pretty_enum enum}}
-{{else}}
-`{{type}}`{{
-#if
- format}} (`{{format}}`){{
-/if
-}}
-{{
-/if
-}}

rust/kcl-lib/src/docs/templates/type.hbs

@@ -1,7 +0,0 @@
----
-title: "{{title}}"
-excerpt: "{{safe_yaml description}}"
-layout: manual
----
-
-{{> schema this}}