Some improvements to make_docs.nu (nushell#1009)

* Add sumcommands table to docs of the root command * Add subcommands table to docs of the root command * Add input/output types for command docs * Add input/output types for command docs * Add commands/docs/from.md example * Mark dataframe commands * Add type for subcommands * ci skip * Add build tips for extra commands * Add build tips for extra commands * ci skip * ci skip
webwurst · Aug 23, 2023 · e0fa47e · e0fa47e
1 parent da40c9d
commit e0fa47e
Show file tree

Hide file tree

Showing 6 changed files with 185 additions and 59 deletions.
diff --git a/commands/docs/dfr_var.md b/commands/docs/dfr_var.md
@@ -1,25 +1,32 @@
 ---
 title: dfr var
 categories: |
- lazyframe
-version: 0.83.0
-lazyframe: |
- Aggregates columns to their var value
+ expression
+version: 0.83.2
+expression: |
+ Create a var expression for an aggregation
 usage: |
- Aggregates columns to their var value
+ Create a var expression for an aggregation
 ---
 
-# <code>{{ $frontmatter.title }}</code> for lazyframe
+# <code>{{ $frontmatter.title }}</code> for expression
 
-<div class='command-title'>{{ $frontmatter.lazyframe }}</div>
+<div class='command-title'>{{ $frontmatter.expression }}</div>
 
 ## Signature
 
 ```> dfr var ```
 
+
+## Input/output types:
+
+| input | output |
+| ----- | ------ |
+| any | any |
+
 ## Examples
 
-Var value from columns in a dataframe
+Var value from columns in a dataframe or aggregates columns to their var value
 ```shell
 > [[a b]; [6 2] [4 2] [2 2]] | dfr into-df | dfr var
 ╭───┬──────┬──────╮
@@ -29,3 +36,21 @@ Var value from columns in a dataframe
 ╰───┴──────┴──────╯
 
 ```
+
+Var aggregation for a group-by
+```shell
+> [[a b]; [one 2] [one 2] [two 1] [two 1]]
+ | dfr into-df
+ | dfr group-by a
+ | dfr agg (dfr col b | dfr var)
+╭───┬─────┬──────╮
+│ # │ a │ b │
+├───┼─────┼──────┤
+│ 0 │ one │ 0.00 │
+│ 1 │ two │ 0.00 │
+╰───┴─────┴──────╯
+
+```
+
+
+**Tips:** Dataframe commands were not shipped in the official binaries by default, you have to build it with `--features=dataframe` flag
diff --git a/commands/docs/format.md b/commands/docs/format.md
@@ -2,7 +2,7 @@
 title: format
 categories: |
  strings
-version: 0.83.0
+version: 0.83.2
 strings: |
  Format columns into a string using a simple pattern.
 usage: |
@@ -21,6 +21,13 @@ usage: |
 
  - `pattern`: the pattern to output. e.g.) "{foo}: {bar}"
 
+
+## Input/output types:
+
+| input | output |
+| ------ | ------------ |
+| record | any |
+| table | list\<string\> |
 ## Examples
 
 Print filenames with their sizes
@@ -38,3 +45,14 @@ Print elements from some columns of a table
 ╰───┴────╯
 
 ```
+
+
+## Subcommands:
+
+| name | type | usage |
+| ------------------------------------------------------ | ------- | -------------------------------------------------------- |
+| [`format date`](/commands/docs/format_date.md) | Builtin | Format a given date using a format string. |
+| [`format duration`](/commands/docs/format_duration.md) | Builtin | Outputs duration with a specified unit of time. |
+| [`format filesize`](/commands/docs/format_filesize.md) | Builtin | Converts a column of filesizes to some specified format. |
+
+**Tips:** Command `format` was not included in the official binaries by default, you have to build it with `--features=extra` flag
diff --git a/commands/docs/from.md b/commands/docs/from.md
@@ -2,7 +2,7 @@
 title: from
 categories: |
  formats
-version: 0.83.0
+version: 0.83.2
 formats: |
  Parse a string or binary data into structured data.
 usage: |
@@ -17,5 +17,33 @@ usage: |
 
 ```> from ```
 
+
+## Input/output types:
+
+| input | output |
+| ------- | ------ |
+| nothing | string |
+
 ## Notes
-You must use one of the following subcommands. Using this command as-is will only produce this help message.
+You must use one of the following subcommands. Using this command as-is will only produce this help message.
+
+## Subcommands:
+
+| name | type | usage |
+| ------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| [`from csv`](/commands/docs/from_csv.md) | Builtin | Parse text as .csv and create table. |
+| [`from eml`](/commands/docs/from_eml.md) | Builtin,Plugin | Parse text as .eml and create record. |
+| [`from ics`](/commands/docs/from_ics.md) | Builtin,Plugin | Parse text as .ics and create table. |
+| [`from ini`](/commands/docs/from_ini.md) | Builtin,Plugin | Parse text as .ini and create table. |
+| [`from json`](/commands/docs/from_json.md) | Builtin | Convert from json to structured data. |
+| [`from nuon`](/commands/docs/from_nuon.md) | Builtin | Convert from nuon to structured data. |
+| [`from ods`](/commands/docs/from_ods.md) | Builtin | Parse OpenDocument Spreadsheet(.ods) data and create table. |
+| [`from ssv`](/commands/docs/from_ssv.md) | Builtin | Parse text as space-separated values and create a table. The default minimum number of spaces counted as a separator is 2. |
+| [`from toml`](/commands/docs/from_toml.md) | Builtin | Parse text as .toml and create record. |
+| [`from tsv`](/commands/docs/from_tsv.md) | Builtin | Parse text as .tsv and create table. |
+| [`from url`](/commands/docs/from_url.md) | Builtin | Parse url-encoded string as a record. |
+| [`from vcf`](/commands/docs/from_vcf.md) | Builtin,Plugin | Parse text as .vcf and create table. |
+| [`from xlsx`](/commands/docs/from_xlsx.md) | Builtin | Parse binary Excel(.xlsx) data and create table. |
+| [`from xml`](/commands/docs/from_xml.md) | Builtin | Parse text as .xml and create record. |
+| [`from yaml`](/commands/docs/from_yaml.md) | Builtin | Parse text as .yaml/.yml and create table. |
+| [`from yml`](/commands/docs/from_yml.md) | Builtin | Parse text as .yaml/.yml and create table. |
diff --git a/commands/docs/into.md b/commands/docs/into.md
@@ -2,7 +2,7 @@
 title: into
 categories: |
  conversions
-version: 0.83.0
+version: 0.83.2
 conversions: |
  Commands to convert data from one type to another.
 usage: |
@@ -17,5 +17,28 @@ usage: |
 
 ```> into ```
 
+
+## Input/output types:
+
+| input | output |
+| ------- | ------ |
+| nothing | string |
+
 ## Notes
-You must use one of the following subcommands. Using this command as-is will only produce this help message.
+You must use one of the following subcommands. Using this command as-is will only produce this help message.
+
+## Subcommands:
+
+| name | type | usage |
+| -------------------------------------------------- | ------- | ------------------------------------------ |
+| [`into binary`](/commands/docs/into_binary.md) | Builtin | Convert value to a binary primitive. |
+| [`into bits`](/commands/docs/into_bits.md) | Builtin | Convert value to a binary primitive. |
+| [`into bool`](/commands/docs/into_bool.md) | Builtin | Convert value to boolean. |
+| [`into datetime`](/commands/docs/into_datetime.md) | Builtin | Convert text or timestamp into a datetime. |
+| [`into decimal`](/commands/docs/into_decimal.md) | Builtin | Convert text into a decimal. |
+| [`into duration`](/commands/docs/into_duration.md) | Builtin | Convert value to duration. |
+| [`into filesize`](/commands/docs/into_filesize.md) | Builtin | Convert value to filesize. |
+| [`into int`](/commands/docs/into_int.md) | Builtin | Convert value to integer. |
+| [`into record`](/commands/docs/into_record.md) | Builtin | Convert value to record. |
+| [`into sqlite`](/commands/docs/into_sqlite.md) | Builtin | Convert table into a SQLite database. |
+| [`into string`](/commands/docs/into_string.md) | Builtin | Convert value to string. |
diff --git a/commands/docs/into_duration.md b/commands/docs/into_duration.md
@@ -2,7 +2,7 @@
 title: into duration
 categories: |
  conversions
-version: 0.83.0
+version: 0.83.2
 conversions: |
  Convert value to duration.
 usage: |
@@ -15,70 +15,54 @@ usage: |
 
 ## Signature
 
-```> into duration ...rest --convert```
+```> into duration ...rest```
 
 ## Parameters
 
  - `...rest`: for a data structure input, convert data at the given cell paths
- - `--convert {string}`: convert duration into another duration
 
-## Notes
-This command does not take leap years into account, and every month is assumed to have 30 days.
-## Examples
 
-Convert string to duration in table
-```shell
-> [[value]; ['1sec'] ['2min'] ['3hr'] ['4day'] ['5wk']] | into duration value
-╭───┬─────────────╮
-│ # │ value │
-├───┼─────────────┤
-│ 0 │ 1sec │
-│ 1 │ 2min │
-│ 2 │ 3hr │
-│ 3 │ 4day │
-│ 4 │ 1month 5day │
-╰───┴─────────────╯
+## Input/output types:
 
-```
+| input | output |
+| -------- | -------- |
+| duration | duration |
+| string | duration |
+| table | table |
+## Examples
 
-Convert string to duration
+Convert duration string to duration value
 ```shell
 > '7min' | into duration
 7min
 ```
 
-Convert string to the requested duration as a string
+Convert compound duration string to duration value
 ```shell
-> '7min' | into duration --convert sec
-420 sec
+> '1day 2hr 3min 4sec' | into duration
+1day 2hr 3min 4sec
 ```
 
-Convert duration to duration
+Convert table of duration strings to table of duration values
 ```shell
-> 420sec | into duration
-7min
-```
-
-Convert duration to the requested duration as a string
-```shell
-> 420sec | into duration --convert ms
-420000 ms
-```
+> [[value]; ['1sec'] ['2min'] ['3hr'] ['4day'] ['5wk']] | into duration value
+╭───┬───────╮
+│ # │ value │
+├───┼───────┤
+│ 0 │ 1sec │
+│ 1 │ 2min │
+│ 2 │ 3hr │
+│ 3 │ 4day │
+│ 4 │ 5wk │
+╰───┴───────╯
 
-Convert µs duration to the requested duration as a string
-```shell
-> 1000000µs | into duration --convert sec
-1 sec
 ```
 
-Convert duration to the µs duration as a string
+Convert duration to duration
 ```shell
-> 1sec | into duration --convert µs
-1000000 µs
+> 420sec | into duration
+7min
 ```
 
-Convert duration to µs as a string if unit asked for was us
-```shell
-> 1sec | into duration --convert us
-1000000 µs
-```
+## Notes
+Max duration value is i64::MAX nanoseconds; max duration time unit is wk (weeks).
diff --git a/make_docs.nu b/make_docs.nu
@@ -12,6 +12,21 @@ def safe-path [] {
  $in | str replace --all '\?' '' | str replace --all ' ' '_'
 }
 
+# NOTE: You should have nushell source code directory sit along with the docs' directory to make it work
+# Get commands in `extra` crate by parsing the source code
+def get-extra-cmds [] {
+ if ('../nushell/crates/nu-cmd-extra/src' | path exists) {
+ cd ..
+ glob nushell/crates/nu-cmd-extra/src/**/*.rs
+ | each { $in | open -r | parse -r 'fn name\(&self\) -> &str \{[\r|\n]\s+\"(?P<name>.+)\"[\r|\n]\s+\}' }
+ | flatten
+ | get name
+ } else {
+ []
+ }
+}
+
+let extra_cmds = get-extra-cmds
 
 # generate the YAML frontmatter of a command
 #
@@ -157,6 +172,19 @@ $"## Notes
 "
  }
 
+ let sigs = scope commands | where name == $command.name | select signatures | get 0 | get signatures | values
+ mut input_output = []
+ for s in $sigs {
+ let input = $s | where parameter_type == 'input' | get 0 | get syntax_shape
+ let output = $s | where parameter_type == 'output' | get 0 | get syntax_shape
+ # FIXME: Parentheses are required here to mutate $input_output, otherwise it won't work, maybe a bug?
+ $input_output = ($input_output | append [[input output]; [$input $output]])
+ }
+ let in_out = if ($input_output | length) > 0 {
+ let markdown = ($input_output | sort-by input | to md --pretty | str replace -a '<' '\<' | str replace -a '>' '\>')
+ ['', '## Input/output types:', '', $markdown, ''] | str join (char newline)
+ } else { '' }
+
  let examples = if ($command.examples | length) > 0 {
  let example_top = $"## Examples(char newline)(char newline)"
 
@@ -179,8 +207,28 @@ $"($example.description)
  ""
  }
 
+ # Typically a root command that has sub commands should be one word command
+ let one_word_cmd = ($command.name | split row ' ' | length) == 1
+ let sub_commands = if $one_word_cmd { scope commands | where name =~ $'^($command.name) ' } else { [] }
+ let type_mapping = {is_builtin: 'Builtin', is_plugin: 'Plugin', is_custom: 'Custom'}
+ let sub_commands = if $one_word_cmd and ($sub_commands | length) > 0 {
+ let commands = $sub_commands
+ | select name usage is_builtin is_plugin is_custom
+ | upsert type {|it| $type_mapping | columns | each {|t| if ($it | get $t) { $type_mapping | get $t } } | str join ',' }
+ | update name { $"[`($in)`]\(/commands/docs/($in | safe-path).md\)" }
+ | select name type usage
+ | to md --pretty
+ ['', '## Subcommands:', '', $commands, ''] | str join (char newline)
+ } else { '' }
+
+ let tips = if $command.name =~ '^dfr' {
+ $'(char nl)**Tips:** Dataframe commands were not shipped in the official binaries by default, you have to build it with `--features=dataframe` flag(char nl)'
+ } else if $command.name in $extra_cmds {
+ $'(char nl)**Tips:** Command `($command.name)` was not included in the official binaries by default, you have to build it with `--features=extra` flag(char nl)'
+ } else { '' }
+
  let doc = (
- ($top + $signatures + $parameters + $extra_usage + $examples )
+ ($top + $signatures + $parameters + $in_out + $examples + $extra_usage + $sub_commands + $tips)
  | lines
  | each {|it| ($it | str trim -r) }
  | str join (char newline)