diff --git a/docs/luneTypes.d.luau b/docs/luneTypes.d.luau index f682294..cb5a785 100644 --- a/docs/luneTypes.d.luau +++ b/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: (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: (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: (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...) -> () --[=[ - 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...) -> () --[=[ - 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...) -> () --[=[ - 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 diff --git a/docs/pages/Getting Started - 1 Installation.md b/docs/pages/Getting Started - 1 Installation.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/pages/Getting Started - 2 Writing Scripts.md b/docs/pages/Getting Started - 2 Writing Scripts.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/pages/Getting Started - 3 Running Scripts.md b/docs/pages/Getting Started - 3 Running Scripts.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/pages/Getting Started - 4 Editor Setup.md b/docs/pages/Getting Started - 4 Editor Setup.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/pages/Getting Started.md b/docs/pages/Getting Started.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/pages/_Sidebar.md b/docs/pages/_Sidebar.md new file mode 100644 index 0000000..da93108 --- /dev/null +++ b/docs/pages/_Sidebar.md @@ -0,0 +1,20 @@ + + +# 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) diff --git a/packages/cli/src/gen/definitions/mod.rs b/packages/cli/src/gen/definitions/mod.rs index 63c3807..fe80f7c 100644 --- a/packages/cli/src/gen/definitions/mod.rs +++ b/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; diff --git a/packages/cli/src/gen/wiki_dir.rs b/packages/cli/src/gen/wiki_dir.rs index 90ea97c..b3ce260 100644 --- a/packages/cli/src/gen/wiki_dir.rs +++ b/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 = ""; -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> = 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 - .get_name() - .context("Missing name for top-level doc item")?; - 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()); + let category_name = + get_name(top_level_item).context("Missing name for top-level doc item")?; + api_reference.insert(category_name, top_level_item.clone()); } DefinitionsItemKind::Function => { - let category = match api_reference.contains_key(CATEGORY_NONE) { - 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()); + no_category.push(top_level_item.clone()); } _ => unimplemented!("Globals other than tables and functions are not yet implemented"), } } - // Generate our api reference folder - let path_api_ref = path_wiki_dir.join("api-reference"); - dirs_to_write.push(path_api_ref.clone()); + // Insert globals with no category into a new "Uncategorized" global + api_reference.insert( + 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 { - if category_items.len() == 1 { - let item = category_items.first().unwrap(); - let path = path_api_ref.join(category_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))); - } 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))); - } - } + for (category_name, category_item) in api_reference { + let path = path_wiki_dir + .join(format!("API Reference - {category_name}")) + .with_extension("md"); + let mut contents = String::new(); + write!(contents, "{GENERATED_COMMENT_TAG}\n\n")?; + generate_markdown_documentation(&mut contents, &category_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 { + 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", - item.get_name().context("Table is missing a name")? - )?; - } - 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")? + "\n{} {}\n", + if item.is_table() { "#" } else { "###" }, + get_name(item)? )?; } DefinitionsItemKind::Description => {