From c5aa15c7f6b3e44b6c211d5e83617ced33424aec Mon Sep 17 00:00:00 2001 From: Stefan Holderbach Date: Sun, 14 Jul 2024 10:10:41 +0200 Subject: [PATCH] Add top-level crate documentation/READMEs (#12907) # Description Add `README.md` files to each crate in our workspace (-plugins) and also include it in the `lib.rs` documentation for (if there is no existing `lib.rs` crate documentation) In all new README I added the defensive comment that the crates are not considered stable for public consumption. If necessary we can adjust this if we deem a crate useful for plugin authors. --- crates/nu-cli/README.md | 7 +++++++ crates/nu-cli/src/lib.rs | 1 + crates/nu-cmd-base/README.md | 5 +++++ crates/nu-cmd-base/src/lib.rs | 1 + crates/nu-cmd-extra/src/lib.rs | 1 + crates/nu-cmd-lang/src/lib.rs | 1 + crates/nu-color-config/README.md | 5 +++++ crates/nu-color-config/src/lib.rs | 1 + crates/nu-command/README.md | 7 +++++++ crates/nu-command/src/lib.rs | 1 + crates/nu-engine/README.md | 9 +++++++++ crates/nu-engine/src/lib.rs | 1 + crates/nu-explore/README.md | 5 +++++ crates/nu-explore/src/lib.rs | 1 + crates/nu-json/README.md | 4 ++-- crates/nu-json/src/lib.rs | 1 + crates/nu-lsp/README.md | 7 +++++++ crates/nu-lsp/src/lib.rs | 1 + crates/nu-parser/README.md | 14 +++++++------- crates/nu-parser/src/lib.rs | 1 + crates/nu-path/src/lib.rs | 1 + crates/nu-protocol/src/lib.rs | 1 + crates/nu-protocol/src/pipeline/byte_stream.rs | 4 ++-- crates/nu-std/README.md | 2 +- crates/nu-std/src/lib.rs | 1 + crates/nu-system/README.md | 7 +++++++ crates/nu-system/src/lib.rs | 1 + crates/nu-table/README.md | 7 +++++++ crates/nu-table/src/lib.rs | 1 + crates/nu-term-grid/README.md | 5 +++++ crates/nu-term-grid/src/lib.rs | 1 + crates/nu-test-support/README.md | 7 +++++++ crates/nu-test-support/src/lib.rs | 1 + crates/nu-utils/README.md | 6 ++++++ crates/nu-utils/src/lib.rs | 1 + crates/nuon/README.md | 2 +- 36 files changed, 109 insertions(+), 13 deletions(-) create mode 100644 crates/nu-cli/README.md create mode 100644 crates/nu-cmd-base/README.md create mode 100644 crates/nu-color-config/README.md create mode 100644 crates/nu-command/README.md create mode 100644 crates/nu-engine/README.md create mode 100644 crates/nu-explore/README.md create mode 100644 crates/nu-lsp/README.md create mode 100644 crates/nu-system/README.md create mode 100644 crates/nu-table/README.md create mode 100644 crates/nu-term-grid/README.md create mode 100644 crates/nu-test-support/README.md create mode 100644 crates/nu-utils/README.md diff --git a/crates/nu-cli/README.md b/crates/nu-cli/README.md new file mode 100644 index 0000000000..e0eca3c9bd --- /dev/null +++ b/crates/nu-cli/README.md @@ -0,0 +1,7 @@ +This crate implements the core functionality of the interactive Nushell REPL and interfaces with `reedline`. +Currently implements the syntax highlighting and completions logic. +Furthermore includes a few commands that are specific to `reedline` + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-cli/src/lib.rs b/crates/nu-cli/src/lib.rs index 6f151adad1..d584802cfb 100644 --- a/crates/nu-cli/src/lib.rs +++ b/crates/nu-cli/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod commands; mod completions; mod config_files; diff --git a/crates/nu-cmd-base/README.md b/crates/nu-cmd-base/README.md new file mode 100644 index 0000000000..28d299928a --- /dev/null +++ b/crates/nu-cmd-base/README.md @@ -0,0 +1,5 @@ +Utilities used by the different `nu-command`/`nu-cmd-*` crates, should not contain any full `Command` implementations. + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-cmd-base/src/lib.rs b/crates/nu-cmd-base/src/lib.rs index 250a57d741..c2608f8466 100644 --- a/crates/nu-cmd-base/src/lib.rs +++ b/crates/nu-cmd-base/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] pub mod formats; pub mod hook; pub mod input_handler; diff --git a/crates/nu-cmd-extra/src/lib.rs b/crates/nu-cmd-extra/src/lib.rs index 2a3d70e6cd..f6f97c2f96 100644 --- a/crates/nu-cmd-extra/src/lib.rs +++ b/crates/nu-cmd-extra/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod example_test; pub mod extra; pub use extra::*; diff --git a/crates/nu-cmd-lang/src/lib.rs b/crates/nu-cmd-lang/src/lib.rs index 427a535d5d..41022cc231 100644 --- a/crates/nu-cmd-lang/src/lib.rs +++ b/crates/nu-cmd-lang/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod core_commands; mod default_context; pub mod example_support; diff --git a/crates/nu-color-config/README.md b/crates/nu-color-config/README.md new file mode 100644 index 0000000000..f03753685c --- /dev/null +++ b/crates/nu-color-config/README.md @@ -0,0 +1,5 @@ +Logic to resolve colors for syntax highlighting and output formatting + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-color-config/src/lib.rs b/crates/nu-color-config/src/lib.rs index 3bd4dc9e4d..77ec9d0e79 100644 --- a/crates/nu-color-config/src/lib.rs +++ b/crates/nu-color-config/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod color_config; mod matching_brackets_style; mod nu_style; diff --git a/crates/nu-command/README.md b/crates/nu-command/README.md new file mode 100644 index 0000000000..1cbb8cd9f2 --- /dev/null +++ b/crates/nu-command/README.md @@ -0,0 +1,7 @@ +This crate contains the majority of our commands + +We allow ourselves to move some of the commands in `nu-command` to `nu-cmd-*` crates as needed. + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-command/src/lib.rs b/crates/nu-command/src/lib.rs index a854fe3507..55c4974325 100644 --- a/crates/nu-command/src/lib.rs +++ b/crates/nu-command/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod bytes; mod charting; mod conversions; diff --git a/crates/nu-engine/README.md b/crates/nu-engine/README.md new file mode 100644 index 0000000000..d5198cfc3f --- /dev/null +++ b/crates/nu-engine/README.md @@ -0,0 +1,9 @@ +This crate primarily drives the evaluation of expressions. + +(Some overlap with nu-protocol) + +- Provides `CallExt` + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-engine/src/lib.rs b/crates/nu-engine/src/lib.rs index 7ed246e975..5a5bb9a5d0 100644 --- a/crates/nu-engine/src/lib.rs +++ b/crates/nu-engine/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod call_ext; mod closure_eval; pub mod column; diff --git a/crates/nu-explore/README.md b/crates/nu-explore/README.md new file mode 100644 index 0000000000..d18a576c43 --- /dev/null +++ b/crates/nu-explore/README.md @@ -0,0 +1,5 @@ +Implementation of the interactive `explore` command pager. + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-explore/src/lib.rs b/crates/nu-explore/src/lib.rs index 043c85eb02..d645572c89 100644 --- a/crates/nu-explore/src/lib.rs +++ b/crates/nu-explore/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod commands; mod default_context; mod explore; diff --git a/crates/nu-json/README.md b/crates/nu-json/README.md index acf3c6b296..c982f1a818 100644 --- a/crates/nu-json/README.md +++ b/crates/nu-json/README.md @@ -24,7 +24,7 @@ nu-json = "0.76" ## From the Commandline Add with: -``` +```sh cargo add serde cargo add nu-json ``` @@ -43,7 +43,7 @@ fn main() { let sample_text=r#" { - # specify rate in requests/second + ## specify rate in requests/second rate: 1000 array: [ diff --git a/crates/nu-json/src/lib.rs b/crates/nu-json/src/lib.rs index eead282786..1cf2c0a9fd 100644 --- a/crates/nu-json/src/lib.rs +++ b/crates/nu-json/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] pub use self::de::{ from_iter, from_reader, from_slice, from_str, Deserializer, StreamDeserializer, }; diff --git a/crates/nu-lsp/README.md b/crates/nu-lsp/README.md new file mode 100644 index 0000000000..d9e666d6c2 --- /dev/null +++ b/crates/nu-lsp/README.md @@ -0,0 +1,7 @@ +Implementation of the Nushell language server. + +See [the Language Server Protocol specification](https://microsoft.github.io/language-server-protocol/) + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-lsp/src/lib.rs b/crates/nu-lsp/src/lib.rs index fdeededac5..aee2ab240d 100644 --- a/crates/nu-lsp/src/lib.rs +++ b/crates/nu-lsp/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] use lsp_server::{Connection, IoThreads, Message, Response, ResponseError}; use lsp_types::{ request::{Completion, GotoDefinition, HoverRequest, Request}, diff --git a/crates/nu-parser/README.md b/crates/nu-parser/README.md index 02f61a31a6..cbb7729e4d 100644 --- a/crates/nu-parser/README.md +++ b/crates/nu-parser/README.md @@ -4,7 +4,7 @@ Nushell's parser is a type-directed parser, meaning that the parser will use typ Nushell's base language is whitespace-separated tokens with the command (Nushell's term for a function) name in the head position: -``` +```nushell head1 arg1 arg2 | head2 ``` @@ -12,7 +12,7 @@ head1 arg1 arg2 | head2 The first job of the parser is to a lexical analysis to find where the tokens start and end in the input. This turns the above into: -``` +```text , , , , ``` @@ -24,7 +24,7 @@ As Nushell is a language of pipelines, pipes form a key role in both separating The above tokens are converted the following during the lite parse phase: -``` +```text Pipeline: Command #1: , , @@ -45,7 +45,7 @@ Each command has a shape assigned to each of the arguments it reads in. These sh For example, if the command is written as: -```sql +```text where $x > 10 ``` @@ -53,7 +53,7 @@ When the parsing happens, the parser will look up the `where` command and find i In the above example, if the Signature of `where` said that it took three String values, the result would be: -``` +```text CallInfo: Name: `where` Args: @@ -64,7 +64,7 @@ CallInfo: Or, the Signature could state that it takes in three positional arguments: a Variable, an Operator, and a Number, which would give: -``` +```text CallInfo: Name: `where` Args: @@ -77,7 +77,7 @@ Note that in this case, each would be checked at compile time to confirm that th Finally, some Shapes can consume more than one token. In the above, if the `where` command stated it took in a single required argument, and that the Shape of this argument was a MathExpression, then the parser would treat the remaining tokens as part of the math expression. -``` +```text CallInfo: Name: `where` Args: diff --git a/crates/nu-parser/src/lib.rs b/crates/nu-parser/src/lib.rs index 3c97012e8a..8f871aa815 100644 --- a/crates/nu-parser/src/lib.rs +++ b/crates/nu-parser/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod deparse; mod exportable; mod flatten; diff --git a/crates/nu-path/src/lib.rs b/crates/nu-path/src/lib.rs index 8553495439..2cb415264a 100644 --- a/crates/nu-path/src/lib.rs +++ b/crates/nu-path/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod assert_path_eq; mod components; pub mod dots; diff --git a/crates/nu-protocol/src/lib.rs b/crates/nu-protocol/src/lib.rs index cae5d3fd0a..e143a19819 100644 --- a/crates/nu-protocol/src/lib.rs +++ b/crates/nu-protocol/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod alias; pub mod ast; pub mod config; diff --git a/crates/nu-protocol/src/pipeline/byte_stream.rs b/crates/nu-protocol/src/pipeline/byte_stream.rs index 69391b39a9..bd384e88c2 100644 --- a/crates/nu-protocol/src/pipeline/byte_stream.rs +++ b/crates/nu-protocol/src/pipeline/byte_stream.rs @@ -159,14 +159,14 @@ impl From for Type { /// Try not to use this method if possible. Rather, please use [`reader`](ByteStream::reader) /// (or [`lines`](ByteStream::lines) if it matches the situation). /// -/// Additionally, there are few methods to collect a [`Bytestream`] into memory: +/// Additionally, there are few methods to collect a [`ByteStream`] into memory: /// - [`into_bytes`](ByteStream::into_bytes): collects all bytes into a [`Vec`]. /// - [`into_string`](ByteStream::into_string): collects all bytes into a [`String`], erroring if utf-8 decoding failed. /// - [`into_value`](ByteStream::into_value): collects all bytes into a value typed appropriately /// for the [type](.type_()) of this stream. If the type is [`Unknown`](ByteStreamType::Unknown), /// it will produce a string value if the data is valid UTF-8, or a binary value otherwise. /// -/// There are also a few other methods to consume all the data of a [`Bytestream`]: +/// There are also a few other methods to consume all the data of a [`ByteStream`]: /// - [`drain`](ByteStream::drain): consumes all bytes and outputs nothing. /// - [`write_to`](ByteStream::write_to): writes all bytes to the given [`Write`] destination. /// - [`print`](ByteStream::print): a convenience wrapper around [`write_to`](ByteStream::write_to). diff --git a/crates/nu-std/README.md b/crates/nu-std/README.md index d6e4d6e9f6..23bd684a50 100644 --- a/crates/nu-std/README.md +++ b/crates/nu-std/README.md @@ -7,7 +7,7 @@ The standard library is a pure-`nushell` collection of custom commands which provide interactive utilities and building blocks for users writing casual scripts or complex applications. To see what's here: -``` +```text > use std > scope commands | select name usage | where name =~ "std " #┬───────────name────────────┬──────────────────────usage────────────────────── diff --git a/crates/nu-std/src/lib.rs b/crates/nu-std/src/lib.rs index a20e3fc5da..ff6910e4ba 100644 --- a/crates/nu-std/src/lib.rs +++ b/crates/nu-std/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] use log::trace; use nu_engine::eval_block; use nu_parser::parse; diff --git a/crates/nu-system/README.md b/crates/nu-system/README.md new file mode 100644 index 0000000000..d847bf4e0f --- /dev/null +++ b/crates/nu-system/README.md @@ -0,0 +1,7 @@ +Operating system specific bindings used by Nushell. + +Currently primarily wrappers around processes and ways to gather process info from the system + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-system/src/lib.rs b/crates/nu-system/src/lib.rs index 2fc97d2e7e..3633d62990 100644 --- a/crates/nu-system/src/lib.rs +++ b/crates/nu-system/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod foreground; #[cfg(target_os = "freebsd")] diff --git a/crates/nu-table/README.md b/crates/nu-table/README.md new file mode 100644 index 0000000000..945d515e62 --- /dev/null +++ b/crates/nu-table/README.md @@ -0,0 +1,7 @@ +The layout logic for Nushell's table viewer. + +See also the separate `table` command implementation + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-table/src/lib.rs b/crates/nu-table/src/lib.rs index 66cc2a3a82..182585f193 100644 --- a/crates/nu-table/src/lib.rs +++ b/crates/nu-table/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod table; mod table_theme; mod types; diff --git a/crates/nu-term-grid/README.md b/crates/nu-term-grid/README.md new file mode 100644 index 0000000000..5bdd32077d --- /dev/null +++ b/crates/nu-term-grid/README.md @@ -0,0 +1,5 @@ +Implementation of the layout engine for the `grid` command. + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-term-grid/src/lib.rs b/crates/nu-term-grid/src/lib.rs index 79b146593f..ca8ccd4e23 100644 --- a/crates/nu-term-grid/src/lib.rs +++ b/crates/nu-term-grid/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] pub mod grid; pub use grid::Grid; diff --git a/crates/nu-test-support/README.md b/crates/nu-test-support/README.md new file mode 100644 index 0000000000..f384b15067 --- /dev/null +++ b/crates/nu-test-support/README.md @@ -0,0 +1,7 @@ +This crate provides utilities for testing of Nushell + +Plugin authors should instead refer to `nu-plugin-test-support` + +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-test-support/src/lib.rs b/crates/nu-test-support/src/lib.rs index 5319830920..c6cadbcbd8 100644 --- a/crates/nu-test-support/src/lib.rs +++ b/crates/nu-test-support/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] pub mod commands; pub mod fs; pub mod locale_override; diff --git a/crates/nu-utils/README.md b/crates/nu-utils/README.md new file mode 100644 index 0000000000..de50a8ae93 --- /dev/null +++ b/crates/nu-utils/README.md @@ -0,0 +1,6 @@ +Collection of small utilities that are shared across Nushell crates. + +This crate should compile early in the crate graph and thus not depend on major dependencies or core-nushell crates itself. +## Internal Nushell crate + +This crate implements components of Nushell and is not designed to support plugin authors or other users directly. diff --git a/crates/nu-utils/src/lib.rs b/crates/nu-utils/src/lib.rs index cb834e5e0f..0c021f1dc9 100644 --- a/crates/nu-utils/src/lib.rs +++ b/crates/nu-utils/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] mod casing; mod deansi; pub mod emoji; diff --git a/crates/nuon/README.md b/crates/nuon/README.md index d11aa8104c..158a9d2e7d 100644 --- a/crates/nuon/README.md +++ b/crates/nuon/README.md @@ -4,7 +4,7 @@ The NUON format is a superset of JSON designed to fit the feel of Nushell. Some of its extra features are - trailing commas are allowed - commas are optional in lists -- quotes are not required around keys or any _bare_ string that do not contain spaces +- quotes are not required around keys or any _bare_ string that do not contain spaces or special characters - comments are allowed, though not preserved when using [`from_nuon`] ## Example