Add example for enter, shells and view-source, update some docs (#4604)

crates/nu-command/src/experimental/view_source.rs

@@ -2,7 +2,8 @@ use nu_engine::CallExt;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
 use nu_protocol::{
-    Category, IntoPipelineData, PipelineData, ShellError, Signature, SyntaxShape, Value,
+    Category, Example, IntoPipelineData, PipelineData, ShellError, Signature, Span, SyntaxShape,
+    Value,
 };
 
 #[derive(Clone)]
@@ -99,4 +100,41 @@ impl Command for ViewSource {
             )),
         }
     }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![
+            Example {
+                description: "View the source of a code block",
+                example: r#"let abc = { echo 'hi' }; view-source $abc"#,
+                result: Some(Value::String {
+                    val: "{ echo 'hi' }".to_string(),
+                    span: Span::test_data(),
+                }),
+            },
+            Example {
+                description: "View the source of a custom command",
+                example: r#"def hi [] { echo 'Hi!' }; view-source hi"#,
+                result: Some(Value::String {
+                    val: "{ echo 'Hi!' }".to_string(),
+                    span: Span::test_data(),
+                }),
+            },
+            Example {
+                description: "View the source of a custom command, which participates in the caller environment",
+                example: r#"def-env foo [] { let-env BAR = 'BAZ' }; view-source foo"#,
+                result: Some(Value::String {
+                    val: "{ let-env BAR = 'BAZ' }".to_string(),
+                    span: Span::test_data(),
+                }),
+            },
+            Example {
+                description: "View the source of a module",
+                example: r#"module mod-foo { export env FOO_ENV { 'BAZ' } }; view-source mod-foo"#,
+                result: Some(Value::String {
+                    val: " export env FOO_ENV { 'BAZ' }".to_string(),
+                    span: Span::test_data(),
+                }),
+            },
+        ]
+    }
 }

crates/nu-command/src/shells/enter.rs

@@ -1,7 +1,7 @@
 use nu_engine::{current_dir, CallExt};
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{Category, PipelineData, ShellError, Signature, SyntaxShape, Value};
+use nu_protocol::{Category, Example, PipelineData, ShellError, Signature, SyntaxShape, Value};
 
 /// Source a file for environment variables.
 #[derive(Clone)]
@@ -105,4 +105,12 @@ impl Command for Enter {
 
         Ok(PipelineData::new(call.head))
     }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![Example {
+            description: "Enter a new shell at path '../dir-foo'",
+            example: r#"enter ../dir-foo"#,
+            result: None,
+        }]
+    }
 }

crates/nu-command/src/shells/shells_.rs

@@ -2,7 +2,7 @@ use nu_engine::current_dir;
 use nu_protocol::ast::Call;
 use nu_protocol::engine::{Command, EngineState, Stack};
 use nu_protocol::{
-    Category, IntoInterruptiblePipelineData, PipelineData, ShellError, Signature, Value,
+    Category, Example, IntoInterruptiblePipelineData, PipelineData, ShellError, Signature, Value,
 };
 
 /// Source a file for environment variables.
@@ -69,4 +69,19 @@ impl Command for Shells {
 
         Ok(output.into_pipeline_data(None))
     }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![
+            Example {
+                description: "Enter a new shell at parent path '..' and show all opened shells",
+                example: r#"enter ..; shells"#,
+                result: None,
+            },
+            Example {
+                description: "Show currently active shell",
+                example: r#"shells | where active == $true"#,
+                result: None,
+            },
+        ]
+    }
 }

docs/commands/enter.md

@@ -13,3 +13,10 @@ Enters a new shell at the given path.
 ## Parameters
 
  -  `path`: the path to enter as a new shell
+
+## Examples
+
+Enter a new shell at path '../dir-foo'
+```shell
+> enter ../dir-foo
+```

docs/commands/gstat.md

@@ -13,4 +13,3 @@ Get the git status of a repo
 ## Parameters
 
  -  `path`: path to repo
-

docs/commands/inc.md

@@ -15,4 +15,3 @@ Increment a value or version. Optionally use the column of a table.
  -  `--major`: increment the major version (eg 1.2.1 -> 2.0.0)
  -  `--minor`: increment the minor version (eg 1.2.1 -> 1.3.0)
  -  `--patch`: increment the patch version (eg 1.2.1 -> 1.2.2)
-

docs/commands/query.md

@@ -9,4 +9,3 @@ Show all the query commands
 ## Signature
 
 ```> query ```
-

docs/commands/query_json.md

@@ -13,4 +13,3 @@ execute json query on json file (open --raw <file> | query json 'query string')
 ## Parameters
 
  -  `query`: json query
-

docs/commands/query_web.md

@@ -8,13 +8,12 @@ execute selector query on html/web
 
 ## Signature
 
-```> query web --query --as_html --attribute --as_table --inspect```
+```> query web --query --as-html --attribute --as-table --inspect```
 
 ## Parameters
 
  -  `--query {string}`: selector query
- -  `--as_html`: return the query output as html
+ -  `--as-html`: return the query output as html
  -  `--attribute {string}`: downselect based on the given attribute
- -  `--as_table {any}`: find table based on column header list
+ -  `--as-table {any}`: find table based on column header list
  -  `--inspect`: run in inspect mode to provide more information for determining column headers
-

docs/commands/query_xml.md

@@ -13,4 +13,3 @@ execute xpath query on xml
 ## Parameters
 
  -  `query`: xpath query
-

docs/commands/shells.md

@@ -9,3 +9,15 @@ Lists all open shells.
 ## Signature
 
 ```> shells ```
+
+## Examples
+
+Enter a new shell at parent path '..' and show all opened shells
+```shell
+> enter ..; shells
+```
+
+Show currently active shell
+```shell
+> shells | where active == $true
+```

docs/commands/view-source.md

@@ -13,3 +13,25 @@ View a block, module, or a definition
 ## Parameters
 
  -  `item`: name or block to view
+
+## Examples
+
+View the source of a code block
+```shell
+> let abc = { echo 'hi' }; view-source $abc
+```
+
+View the source of a custom command
+```shell
+> def hi [] { echo 'Hi!' }; view-source hi
+```
+
+View the source of a custom command, which participates in the caller environment
+```shell
+> def-env foo [] { let-env BAR = 'BAZ' }; view-source foo
+```
+
+View the source of a module
+```shell
+> module mod-foo { export env FOO_ENV { 'BAZ' } }; view-source mod-foo
+```