Add all pages & sidebar for wiki, make naming of global types more consistent

docs/luneTypes.d.luau

@@ -1,6 +1,6 @@
 --[=[
 	@type FsWriteOptions
-	@within fs
+	@within FS
 
 	Options for filesystem APIs what write to files and/or directories.
 
@@ -13,13 +13,13 @@ export type FsWriteOptions = {
 }
 
 --[=[
-	@class fs
+	@class FS
 	
 	Filesystem
 ]=]
 declare fs: {
 	--[=[
-		@within fs
+		@within FS
 		@must_use
 
 		Reads a file at `path`.
@@ -36,7 +36,7 @@ declare fs: {
 	]=]
 	readFile: (path: string) -> string,
 	--[=[
-		@within fs
+		@within FS
 		@must_use
 
 		Reads entries in a directory at `path`.
@@ -52,7 +52,7 @@ declare fs: {
 	]=]
 	readDir: (path: string) -> { string },
 	--[=[
-		@within fs
+		@within FS
 
 		Writes to a file at `path`.
 
@@ -67,7 +67,7 @@ declare fs: {
 	]=]
 	writeFile: (path: string, contents: string) -> (),
 	--[=[
-		@within fs
+		@within FS
 
 		Creates a directory and its parent directories if they are missing.
 
@@ -81,7 +81,7 @@ declare fs: {
 	]=]
 	writeDir: (path: string) -> (),
 	--[=[
-		@within fs
+		@within FS
 
 		Removes a file.
 
@@ -95,7 +95,7 @@ declare fs: {
 	]=]
 	removeFile: (path: string) -> (),
 	--[=[
-		@within fs
+		@within FS
 
 		Removes a directory and all of its contents.
 
@@ -109,7 +109,7 @@ declare fs: {
 	]=]
 	removeDir: (path: string) -> (),
 	--[=[
-		@within fs
+		@within FS
 		@must_use
 
 		Checks if a given path is a file.
@@ -124,7 +124,7 @@ declare fs: {
 	]=]
 	isFile: (path: string) -> boolean,
 	--[=[
-		@within fs
+		@within FS
 		@must_use
 
 		Checks if a given path is a directory.
@@ -139,7 +139,7 @@ declare fs: {
 	]=]
 	isDir: (path: string) -> boolean,
 	--[=[
-		@within fs
+		@within FS
 
 		Moves a file or directory to a new path.
 
@@ -164,7 +164,7 @@ type NetMethod = "GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "PATCH
 
 --[=[
 	@type NetFetchParams
-	@within net
+	@within Net
 
 	Parameters for sending network requests with `net.request`.
 
@@ -208,7 +208,7 @@ export type NetFetchResponse = {
 
 --[=[
 	@type NetRequest
-	@within net
+	@within Net
 
 	Data type for requests in `net.serve`.
 
@@ -230,7 +230,7 @@ export type NetRequest = {
 
 --[=[
 	@type NetRequest
-	@within net
+	@within Net
 	
 	Response type for requests in `net.serve`.
 
@@ -251,7 +251,7 @@ type NetServeWebSocketHandler = (socket: NetWebSocket) -> ()
 
 --[=[
 	@type NetServeConfig
-	@within net
+	@within Net
 
 	Configuration for `net.serve`.
 
@@ -267,7 +267,7 @@ export type NetServeConfig = {
 
 --[=[
 	@type NetServeHandle
-	@within net
+	@within Net
 
 	A handle to a currently running web server, containing a single `stop` function to gracefully shut down the web server.
 ]=]
@@ -277,7 +277,7 @@ export type NetServeHandle = {
 
 --[=[
 	@type NetWebSocket
-	@within net
+	@within Net
 
 	A reference to a web socket connection.
 	
@@ -302,13 +302,13 @@ declare class NetWebSocket
 end
 
 --[=[
-	@class net
+	@class Net
 
 	Networking
 ]=]
 declare net: {
 	--[=[
-		@within net
+		@within Net
 
 		Sends an HTTP request using the given url and / or parameters, and returns a dictionary that describes the response received.
 		
@@ -319,7 +319,7 @@ declare net: {
 	]=]
 	request: (config: string | NetFetchParams) -> NetFetchResponse,
 	--[=[
-		@within net
+		@within Net
 		@must_use
 
 		Connects to a web socket at the given URL.
@@ -332,7 +332,7 @@ declare net: {
 	]=]
 	socket: (url: string) -> NetWebSocket,
 	--[=[
-		@within net
+		@within Net
 
 		Creates an HTTP server that listens on the given `port`.
 
@@ -344,7 +344,7 @@ declare net: {
 	]=]
 	serve: (port: number, handlerOrConfig: NetServeHttpHandler | NetServeConfig) -> NetServeHandle,
 	--[=[
-		@within net
+		@within Net
 		@must_use
 
 		Encodes the given value as JSON.
@@ -355,7 +355,7 @@ declare net: {
 	]=]
 	jsonEncode: (value: any, pretty: boolean?) -> string,
 	--[=[
-		@within net
+		@within Net
 		@must_use
 
 		Decodes the given JSON string into a lua value.
@@ -370,7 +370,7 @@ type ProcessSpawnOptionsStdio = "inherit" | "default"
 
 --[=[
 	@type ProcessSpawnOptions
-	@within process
+	@within Process
 
 	A dictionary of options for `process.spawn`, with the following available values:
 
@@ -388,7 +388,7 @@ export type ProcessSpawnOptions = {
 
 --[=[
 	@type ProcessSpawnResult
-	@within process
+	@within Process
 
 	Result type for child processes in `process.spawn`.
 
@@ -407,13 +407,13 @@ export type ProcessSpawnResult = {
 }
 
 --[=[
-	@class process
+	@class Process
 
 	Current process & child processes
 ]=]
 declare process: {
 	--[=[
-		@within process
+		@within Process
 		@read_only
 		
 		The current operating system being used.
@@ -426,7 +426,7 @@ declare process: {
 	]=]
 	os: "linux" | "macos" | "windows",
 	--[=[
-		@within process
+		@within Process
 		@read_only
 		
 		The architecture of the processor currently being used.
@@ -438,21 +438,21 @@ declare process: {
 	]=]
 	arch: "x86_64" | "aarch64",
 	--[=[
-		@within process
+		@within Process
 		@read_only
 
 		The arguments given when running the Lune script.
 	]=]
 	args: { string },
 	--[=[
-		@within process
+		@within Process
 		@read_only
 
 		The current working directory in which the Lune script is running.
 	]=]
 	cwd: string,
 	--[=[
-		@within process
+		@within Process
 		@read_write
 
 		Current environment variables for this process.
@@ -461,7 +461,7 @@ declare process: {
 	]=]
 	env: { [string]: string? },
 	--[=[
-		@within process
+		@within Process
 
 		Exits the currently running script as soon as possible with the given exit code.
 
@@ -473,7 +473,7 @@ declare process: {
 	]=]
 	exit: (code: number?) -> (),
 	--[=[
-		@within process
+		@within Process
 		
 		Spawns a child process that will run the program `program`, and returns a dictionary that describes the final status and ouput of the child process.
 
@@ -495,13 +495,13 @@ declare process: {
 }
 
 --[=[
-	@class stdio
+	@class Stdio
 
 	Standard input / output & utility functions 
 ]=]
 declare stdio: {
 	--[=[
-		@within stdio
+		@within Stdio
 		@must_use
 
 		Return an ANSI string that can be used to modify the persistent output color.
@@ -522,7 +522,7 @@ declare stdio: {
 	]=]
 	color: (color: "reset" | "black" | "red" | "green" | "yellow" | "blue" | "purple" | "cyan" | "white") -> string,
 	--[=[
-		@within stdio
+		@within Stdio
 		@must_use
 
 		Return an ANSI string that can be used to modify the persistent output style.
@@ -543,7 +543,7 @@ declare stdio: {
 	]=]
 	style: (style: "reset" | "bold" | "dim") -> string,
 	--[=[
-		@within stdio
+		@within Stdio
 		@must_use
 
 		Formats arguments into a human-readable string with syntax highlighting for tables.
@@ -553,7 +553,7 @@ declare stdio: {
 	]=]
 	format: (...any) -> string,
 	--[=[
-		@within stdio
+		@within Stdio
 
 		Writes a string directly to stdout, without any newline.
 
@@ -561,7 +561,7 @@ declare stdio: {
 	]=]
 	write: (s: string) -> (),
 	--[=[
-		@within stdio
+		@within Stdio
 
 		Writes a string directly to stderr, without any newline.
 
@@ -569,7 +569,7 @@ declare stdio: {
 	]=]
 	ewrite: (s: string) -> (),
 	--[=[
-		@within stdio
+		@within Stdio
 		@must_use
 
 		Prompts for user input using the wanted kind of prompt:
@@ -594,13 +594,13 @@ declare stdio: {
 }
 
 --[=[
-	@class task
+	@class Task
 
 	Task scheduler & thread spawning
 ]=]
 declare task: {
 	--[=[
-		@within task
+		@within Task
 
 		Stops a currently scheduled thread from resuming.
 
@@ -608,7 +608,7 @@ declare task: {
 	]=]
 	cancel: (thread: thread) -> (),
 	--[=[
-		@within task
+		@within Task
 
 		Defers a thread or function to run at the end of the current task queue.
 
@@ -617,7 +617,7 @@ declare task: {
 	]=]
 	defer: <T...>(functionOrThread: thread | (T...) -> (...any), T...) -> thread,
 	--[=[
-		@within task
+		@within Task
 
 		Delays a thread or function to run after `duration` seconds.
 
@@ -626,7 +626,7 @@ declare task: {
 	]=]
 	delay: <T...>(duration: number?, functionOrThread: thread | (T...) -> (...any), T...) -> thread,
 	--[=[
-		@within task
+		@within Task
 
 		Instantly runs a thread or function.
 		
@@ -638,7 +638,7 @@ declare task: {
 	]=]
 	spawn: <T...>(functionOrThread: thread | (T...) -> (...any), T...) -> thread,
 	--[=[
-		@within task
+		@within Task
 
 		Waits for the given duration, with a minimum wait time of 10 milliseconds.
 
@@ -656,21 +656,21 @@ declare task: {
 declare print: <T...>(T...) -> ()
 
 --[=[
-	Prints given value(s) to stdout with a leading "[INFO]" tag.
+	Prints given value(s) to stdout with a leading `[INFO]` tag.
 
 	This will format and prettify values such as tables, numbers, booleans, and more.
 ]=]
 declare info: <T...>(T...) -> ()
 
 --[=[
-	Prints given value(s) to stdout with a leading "[WARN]" tag.
+	Prints given value(s) to stdout with a leading `[WARN]` tag.
 
 	This will format and prettify values such as tables, numbers, booleans, and more.
 ]=]
 declare warn: <T...>(T...) -> ()
 
 --[=[
-	Throws an error and prints a formatted version of it with a leading "[ERROR]" tag.
+	Throws an error and prints a formatted version of it with a leading `[ERROR]` tag.
 
 	@param message The error message to throw
 	@param level The stack level to throw the error at, defaults to 0

docs/pages/_Sidebar.md

@@ -0,0 +1,20 @@
+<!-- markdownlint-disable MD025 -->
+
+# Home
+
+- [Home](https://github.com/filiptibell/lune/wiki)
+- [Getting Started](https://github.com/filiptibell/lune/wiki/getting-started)
+  - [1. Installation](https://github.com/filiptibell/lune/wiki/getting-started-1-installation)
+  - [2. Writing Scripts](https://github.com/filiptibell/lune/wiki/getting-started-2-writing-scripts)
+  - [3. Running Scripts](https://github.com/filiptibell/lune/wiki/getting-started-3-running-scripts)
+  - [4. Editor Setup](https://github.com/filiptibell/lune/wiki/getting-started-4-editor-setup)
+- [Advanced Usage](https://github.com/filiptibell/lune/wiki/advanced-usage)
+
+# API Reference
+
+- [FS](https://github.com/filiptibell/lune/wiki/api-reference-fs)
+- [Net](https://github.com/filiptibell/lune/wiki/api-reference-net)
+- [Process](https://github.com/filiptibell/lune/wiki/api-reference-process)
+- [Stdio](https://github.com/filiptibell/lune/wiki/api-reference-stdio)
+- [Task](https://github.com/filiptibell/lune/wiki/api-reference-task)
+- [Uncategorized](https://github.com/filiptibell/lune/wiki/api-reference-uncategorized)

packages/cli/src/gen/definitions/mod.rs

@@ -7,6 +7,7 @@ mod tag;
 mod tree;
 mod type_info_ext;
 
+pub use builder::DefinitionsItemBuilder;
 pub use item::DefinitionsItem;
 pub use kind::DefinitionsItemKind;
 pub use tag::DefinitionsItemTag;

packages/cli/src/gen/wiki_dir.rs

@@ -5,10 +5,18 @@ use anyhow::{Context, Result};
 use futures_util::future::try_join_all;
 use tokio::fs::{create_dir_all, write};
 
-use super::definitions::{DefinitionsItem, DefinitionsItemKind, DefinitionsTree};
+use super::definitions::{
+    DefinitionsItem, DefinitionsItemBuilder, DefinitionsItemKind, DefinitionsItemTag,
+    DefinitionsTree,
+};
 
 const GENERATED_COMMENT_TAG: &str = "<!-- @generated with lune-cli -->";
-const CATEGORY_NONE: &str = "uncategorized";
+const CATEGORY_NONE_NAME: &str = "Uncategorized";
+const CATEGORY_NONE_DESC: &str = "
+All globals that are not available under a specific scope.
+
+These are to be used directly without indexing a global table first.
+";
 
 pub async fn generate_from_type_definitions(contents: &str) -> Result<()> {
     let tree = DefinitionsTree::from_type_definitions(contents)?;
@@ -22,7 +30,8 @@ pub async fn generate_from_type_definitions(contents: &str) -> Result<()> {
     let path_wiki_dir = path_root.join("wiki");
     dirs_to_write.push(path_wiki_dir.clone());
     // Sort doc items into subcategories based on globals
-    let mut api_reference: HashMap<&str, Vec<DefinitionsItem>> = HashMap::new();
+    let mut api_reference = HashMap::new();
+    let mut no_category = Vec::new();
     for top_level_item in tree
         .children()
         .iter()
@@ -30,57 +39,41 @@ pub async fn generate_from_type_definitions(contents: &str) -> Result<()> {
     {
         match top_level_item.kind() {
             DefinitionsItemKind::Table => {
-                let category_name = top_level_item
+                let category_name =
-                    .get_name()
+                    get_name(top_level_item).context("Missing name for top-level doc item")?;
-                    .context("Missing name for top-level doc item")?;
+                api_reference.insert(category_name, top_level_item.clone());
-                let category = match api_reference.contains_key(category_name) {
-                    true => api_reference.get_mut(category_name).unwrap(),
-                    false => {
-                        api_reference.insert(category_name, vec![]);
-                        api_reference.get_mut(category_name).unwrap()
-                    }
-                };
-                category.push(top_level_item.clone());
             }
             DefinitionsItemKind::Function => {
-                let category = match api_reference.contains_key(CATEGORY_NONE) {
+                no_category.push(top_level_item.clone());
-                    true => api_reference.get_mut(CATEGORY_NONE).unwrap(),
-                    false => {
-                        api_reference.insert(CATEGORY_NONE, vec![]);
-                        api_reference.get_mut(CATEGORY_NONE).unwrap()
-                    }
-                };
-                category.push(top_level_item.clone());
             }
             _ => unimplemented!("Globals other than tables and functions are not yet implemented"),
         }
     }
-    // Generate our api reference folder
+    // Insert globals with no category into a new "Uncategorized" global
-    let path_api_ref = path_wiki_dir.join("api-reference");
+    api_reference.insert(
-    dirs_to_write.push(path_api_ref.clone());
+        CATEGORY_NONE_NAME.to_string(),
+        DefinitionsItemBuilder::new()
+            .with_kind(DefinitionsItemKind::Table)
+            .with_name("Uncategorized")
+            .with_children(&no_category)
+            .with_child(
+                DefinitionsItemBuilder::new()
+                    .with_kind(DefinitionsItemKind::Description)
+                    .with_value(CATEGORY_NONE_DESC)
+                    .build()?,
+            )
+            .build()
+            .unwrap(),
+    );
     // Generate files for all subcategories
-    for (category_name, category_items) in api_reference {
+    for (category_name, category_item) in api_reference {
-        if category_items.len() == 1 {
+        let path = path_wiki_dir
-            let item = category_items.first().unwrap();
+            .join(format!("API Reference - {category_name}"))
-            let path = path_api_ref.join(category_name).with_extension("md");
+            .with_extension("md");
-            let mut contents = String::new();
+        let mut contents = String::new();
-            write!(contents, "{GENERATED_COMMENT_TAG}\n\n")?;
+        write!(contents, "{GENERATED_COMMENT_TAG}\n\n")?;
-            generate_markdown_documentation(&mut contents, item)?;
+        generate_markdown_documentation(&mut contents, &category_item)?;
-            files_to_write.push((path, post_process_docs(contents)));
+        files_to_write.push((path, post_process_docs(contents)));
-        } else {
-            let path_subcategory = path_api_ref.join(category_name);
-            dirs_to_write.push(path_subcategory.clone());
-            for item in category_items {
-                let item_name = item
-                    .get_name()
-                    .context("Missing name for subcategory doc item")?;
-                let path = path_subcategory.join(item_name).with_extension("md");
-                let mut contents = String::new();
-                write!(contents, "{GENERATED_COMMENT_TAG}\n\n")?;
-                generate_markdown_documentation(&mut contents, &item)?;
-                files_to_write.push((path, post_process_docs(contents)));
-            }
-        }
     }
     // Write all dirs and files only when we know generation was successful
     let futs_dirs = dirs_to_write
@@ -96,27 +89,34 @@ pub async fn generate_from_type_definitions(contents: &str) -> Result<()> {
     Ok(())
 }
 
+fn get_name(item: &DefinitionsItem) -> Result<String> {
+    item.children()
+        .iter()
+        .find_map(|child| {
+            if child.is_tag() {
+                if let Ok(DefinitionsItemTag::Class(c)) = DefinitionsItemTag::try_from(child) {
+                    Some(c)
+                } else {
+                    None
+                }
+            } else {
+                None
+            }
+        })
+        .or_else(|| item.get_name().map(ToString::to_string))
+        .context("Definitions item is missing a name")
+}
+
 fn generate_markdown_documentation(contents: &mut String, item: &DefinitionsItem) -> Result<()> {
     match item.kind() {
-        DefinitionsItemKind::Table => {
+        DefinitionsItemKind::Table
+        | DefinitionsItemKind::Property
+        | DefinitionsItemKind::Function => {
             write!(
                 contents,
-                "\n# {}\n",
+                "\n{} {}\n",
-                item.get_name().context("Table is missing a name")?
+                if item.is_table() { "#" } else { "###" },
-            )?;
+                get_name(item)?
-        }
-        DefinitionsItemKind::Property => {
-            write!(
-                contents,
-                "\n### `{}`\n",
-                item.get_name().context("Property is missing a name")?
-            )?;
-        }
-        DefinitionsItemKind::Function => {
-            write!(
-                contents,
-                "\n### `{}`\n",
-                item.get_name().context("Function is missing a name")?
             )?;
         }
         DefinitionsItemKind::Description => {