lune-org/lune
1
1
Fork 0
mirror of https://github.com/lune-org/lune.git synced 2024-12-12 13:00:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

Browse source
This commit is contained in:
Filip Tibell 2023-02-23 16:07:09 +01:00
parent e0cae3139f
commit 3a57e1fdc2
No known key found for this signature in database
9 changed files with 134 additions and 113 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

98
docs/luneTypes.d.luau
View file

@ -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

0
docs/pages/Getting Started - 1 Installation.md Normal file
View file

0
docs/pages/Getting Started - 2 Writing Scripts.md Normal file
View file

0
docs/pages/Getting Started - 3 Running Scripts.md Normal file
View file

0
docs/pages/Getting Started - 4 Editor Setup.md Normal file
View file

0
docs/pages/Getting Started.md Normal file
View file

20
docs/pages/_Sidebar.md Normal file
View file

@ -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)

1
packages/cli/src/gen/definitions/mod.rs
View file

@ -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;

122
packages/cli/src/gen/wiki_dir.rs
View file

@ -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
.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");
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, item)?;
generate_markdown_documentation(&mut contents, &category_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)));
}
}
}
// 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",
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 => {