nushell-prophet / numd

numd - reproducible Nushell Markdown documents

numd - reproducible Nushell Markdown documents

Execute chunks of nushell code within markdown documents, write results back to your .md document or output them to the terminal.

numd is inspired by R Markdown.

Quickstart

# this block won't run as it has option `no-run` in its code fence
> git clone https://github.com/nushell-prophet/numd; cd numd
> nupm install --force --path . # optionally you can install this module via nupm
> use numd
> numd run README.md --no-save

How it works

numd run parses the initial file, generates a script to execute the found commands, executes this script in a new nushell instance, parses the results, updates the initial document accordingly, and/or outputs the resulting document into the terminal along with basic changes stats.

Experienced nushell users can understand the logic better by looking at examples. Especially, seeing numd in action describing its own commands.

Details of parsing

1. numd looks for ```nushell or ```nu code chunks.
2. In the code chunks, that entirely don't have lines starting with the > symbol, numd executes the whole code chunks as they are, and if they produce any output (like in print 'this'), then the output is written in the ```output-numd chunks, next to the executed code chunks.
3. In the code chunks that contain one or more lines starting with > symbol, numd filters only lines that start with the > or # symbol, executes those lines one by one and output their results just after the executed line.

numd run flags and params

use numd
numd run --help

run nushell code chunks in a markdown file, outputs results back to the `.md` and optionally to terminal

Usage:
  > run {flags} <file> 

Flags:
  -o, --output-md-path <Filepath> - path to a resulting `.md` file; if omitted, updates the original file
  --echo - output resulting markdown to the terminal
  --no-backup - overwrite the existing `.md` file without backup
  --no-save - do not save changes to the `.md` file
  --no-info - do not output stats of changes in `.md` file
  --intermid-script <Filepath> - optional a path for an intermediate script (useful for debugging purposes)
  --no-fail-on-error - skip errors (and don't update markdown anyway)
  --prepend-intermid <String> - prepend text (code) into the intermid script, useful for customizing nushell output settings
  --diff - use diff for printing changes
  -h, --help - Display the help message for this command

Parameters:
  file <path>: path to a `.md` file containing nushell code to be executed

Input/output types:
  ╭──input──┬─output──╮
  │ nothing │ nothing │
  │ nothing │ string  │
  │ nothing │ record  │
  ╰──input──┴─output──╯

Supported nushell code block options

numd understands the following block options. Several commaseparated block options will be combined together. The block options should be in the infostring of the opening code fence like the example: ```nushell try, new-instance

numd code-block-options --list

╭─────long──────┬─short─┬──────────────────description──────────────────╮
│ no-output     │ O     │ don't try printing result                     │
│ try           │ t     │ try handling errors                           │
│ new-instance  │ n     │ execute the chunk in the new nushell instance │
│ no-run        │ N     │ don't execute the code in chunk               │
│ indent-output │ i     │ indent the output visually                    │
╰─────long──────┴─short─┴──────────────────description──────────────────╯

Stats of changes

By default numd provides basic stats on changes made.

numd run examples/1_simple_markdown/simple_markdown_with_no_output.md --no-save

╭────────────────┬───────────────────────────────────╮
│ filename       │ simple_markdown_with_no_output.md │
│ nu_code_blocks │ 3                                 │
│ levenstein     │ 38                                │
│ diff-lines     │ +5 (20%)                          │
│ diff-words     │ +7 (9.6%)                         │
│ diff-chars     │ +38 (8.8%)                        │
╰────────────────┴───────────────────────────────────╯

Also --diff param can be used to display diff of changes.

numd run examples/1_simple_markdown/simple_markdown_with_no_output.md --diff --no-save --no-info

//    ls; # mind that this ls won't print in the markdown as it is used without `echo` or `>`
//    $var1 | path join 'baz' 'bar'
//    ```
//  + ```output-numd
//  + foo/baz/bar
//  + ```
//    
//    ## Example 3
//    
//    ```nu
//    # This chunk will output results inline
//    > whoami
//  + user
//    > 2 + 2
//  + 4
//    ```

numd clear-outputs

> numd clear-outputs --help
remove numd execution outputs from the file

Usage:
  > clear-outputs {flags} <file> 

Flags:
  -o, --output-md-path <Filepath> - path to a resulting `.md` file; if omitted, updates the original file
  --echo - output resulting markdown to the terminal instead of writing to file
  --strip-markdown - keep only nushell script, strip all markdown tags
  -h, --help - Display the help message for this command

Parameters:
  file <path>: path to a `.md` file containing numd output to be cleared

Input/output types:
  ╭──input──┬─output──╮
  │ nothing │ nothing │
  │ nothing │ string  │
  │ nothing │ record  │
  ╰──input──┴─output──╯

numd catpure

numd can use the display_output hook to write the current sesssion prompts together with their output into a specified markdown file. There are corresponding commands numd capture start and numd capture stop.

> numd capture start --help
start capturing commands and their results into a file

Usage:
  > start (file) 

Flags:
  -h, --help - Display the help message for this command

Parameters:
  file <path>:  (optional, default: 'numd_capture.md')

Input/output types:
  ╭──input──┬─output──╮
  │ nothing │ nothing │
  ╰──input──┴─output──╯

> numd capture stop --help
stop capturing commands and their results

Usage:
  > stop 

Flags:
  -h, --help - Display the help message for this command

Input/output types:
  ╭──input──┬─output──╮
  │ nothing │ nothing │
  ╰──input──┴─output──╯

Some random familiar examples

> ls examples | sort-by name | reject modified size
╭─────────────────name──────────────────┬─type─╮
│ examples/1_simple_markdown            │ dir  │
│ examples/2_numd_commands_explanations │ dir  │
│ examples/3_book_types_of_data         │ dir  │
│ examples/4_book_working_with_lists    │ dir  │
╰─────────────────name──────────────────┴─type─╯

> sys | get host.boot_time
2024-04-07T05:26:21+00:00
> 2 + 2
4
> git tag | lines | sort -n | last
0.1.1

Real fight examples to try

numd run examples/1_simple_markdown/simple_markdown.md --echo --no-save
numd run examples/3_book_types_of_data/types_of_data.md --output-md-path examples/3_book_types_of_data/types_of_data_out.md --no-backup --intermid-script-path examples/3_book_types_of_data/types_of_data.md_intermid.nu

numd's Issues

errors handling and signaling

to find a convinient way to have multiline commands

As the numd file format presupposes the output of commands to be stored in the same document, it's not obvious how to safely and conveniently write multiline commands distinguishing them with command execution outputs.

I have a few ideas:

1. Use the ; delimiter at the end of multiline command (it means that all symbols between the previous > and the furthest line that ends with ; would be executed as one command)
2. Don't use > symbol at the beginning of line. If no > symbol in a nushell-code block is found, the entire block is treated as a multiline command and remains unchanged. However, after it, a new code block with output like numd-out is added.

Add handling of the hash symbol in the code.

lazy-tests name

I asked gpt4 the following question:

I have developed a nushell module, that can execute nushell code chunks in arbitrary markdown documents, and output the results back to markdown documents.

If those documents will be placed in some git repository, then when updating those markdown documents may serve as unit tests for the commands in them.

I would like to name this concept lazy-tests. Is this name misleading? Are there similar concepts in computer science already?

---

And it responded to me:

Your concept of "lazy-tests" within markdown documents that contain executable nushell code chunks is both innovative and practical, especially for documentation that needs to stay current with the code it describes. When considering your question about the suitability of the term "lazy-tests" and connections to existing concepts, there are a few points to consider:

Understanding "Lazy-Tests"

The name "lazy-tests" intuitively suggests tests that are not run proactively but rather on-demand or under certain conditions, such as when the documentation is updated or when the code within the markdown documents is executed. This approach has a few parallels in software development and testing:

1. Lazy Evaluation - In programming languages (especially functional ones), lazy evaluation delays the evaluation of an expression until its value is needed. Your "lazy-tests" concept similarly delays the execution of tests until the documentation is updated or checked, mirroring this "on-demand" strategy.

2. Regression Testing - This involves re-running tests on existing software applications to ensure that changes or updates have not introduced new errors. By integrating tests into your markdown documentation, you're effectively setting up a system for regression testing whenever the documents or associated code are updated.

3. Literate Programming - Your system also recalls aspects of literate programming, where a computer program is given as an explanation, in the narrative of human language, interspersed with snippets of macros and source code. However, your approach uniquely executes within markdown files and checks the validity of embedded code, aligning with documentation's goals to be accurate and up-to-date.

4. Continuous Integration (CI) Documentation Testing - In CI practices, automated tests run whenever changes are committed to a repository. While typically focused on the codebase, this concept has been extended to documentation (doc tests) to ensure that examples and guides are not outdated. Your "lazy-tests" could form a part of this broader testing strategy, focusing on verifying the correctness and relevance of documented code snippets.

Is "Lazy-Tests" Misleading?

While the term "lazy" captures the on-demand nature of your testing approach, it might not fully communicate the proactive goal of keeping documentation accurate and reliable. Alternatives could include:

• Documentation-Driven Tests (DDTs)
• On-Demand Doc Tests
• Live Markdown Testing
• Embedded Code Testing (ECT)

Choosing a name depends on what aspect you want to emphasize: the integration within markdown documents, the on-demand nature of these tests, or their role in maintaining documentation quality.

Conclusion

In summary, your idea aligns with several existing concepts but presents a unique approach focused on documentation. The term "lazy-tests" is not misleading per se, but clarifying its exact operation and goals might benefit from a more descriptive name or a detailed explanation accompanying its introduction. Regardless of the terminology, it's a promising approach to ensuring the accuracy and effectiveness of technical documentation, especially in fast-moving projects with frequent updates.

add support for executing examples in help pages

like

> ls --help | nudoc run

add output type `to png`

We can use https://github.com/FMotalleb/nu_plugin_image/

add support for variable declarations

Nudoc is pretty dumb now and just puts all the commands inside the parentheses of the first print argument. Though variables are scoped within those parentheses and because of that, they are unavailable further.