Documentation incorrectly states cal command outputs table instead of string by default

[adamrokickirns]

As the title says, documentation doesn't match the actual functionality:

https://www.nushell.sh/commands/docs/cal.html#input-output-types

I earlier assumed incorrectly it was a bug in cal instead of an error in documentation before editing this issue to it's current form, will move this if documentation errors shouldn't be filed as issues.

[fdncred]

You can get table output using the --as-table flag as the help indicates.

[adamrokickirns]

You can get table output using the --as-table flag as the help indicates.

Ah nevermind then, I somehow missed that. Still, the documentation website does seem to be incorrect in that case:
https://www.nushell.sh/commands/docs/cal.html#input-output-types

Should I close the issue and report the documentation error somewhere else?

In the meantime I'll edit the issue.

[fdncred]

@hustcer any ideas why cal's help doesn't match what it says in the repl?

[raoulkent]

@fdncred is it not due to the

            .input_output_types(vec![
                (Type::Nothing, Type::table()),
                (Type::Nothing, Type::String),
            ])

found here; https://github.com/nushell/nushell/blob/222c30764859a5c78c11c233ae1c1521356c026b/crates/nu-command/src/generators/cal.rs#L49 ?

I am not familiar with the doc generation details, but I was thinking that if the first item of the vec is the one that is selected for the table generation, then that'd explain things.

[fdncred]

Whatever cal --help says should be in the docs.

[raoulkent]

Ahh, fair enough. Seems that cal --help does indeed output the correct table.

[fdncred]

Yup, that's what I'm saying is wrong. It's probably just an old version of the docs that hasn't been updated in a while. @hustcer does those updates usually.

[raoulkent]

Ahh gotcha.

[hustcer]

I will check it later

[raoulkent]

I was thinking about this issue a little more. And just to validate the current state of affairs is that the docs are generated and committed/PR'd manually? I checked the https://github.com/nushell/nushell/blob/main/devdocs/FAQ.md and https://github.com/nushell/nushell/blob/main/CONTRIBUTING.md but found no instructions for the process.

If that is the case I was thinking that this surely must be possible to automate with a GH workflow that either runs on a cron basis / some other trigger to automatically create a PR with the generated docs changes?

If you can push me in the right direction I could pick up the work of creating a cron based workflow to autocreate docs in new PR's or something along those lines?

Edit: Ah, I suppose it is this; https://github.com/nushell/nushell.github.io/blob/main/make_docs.nu

[raoulkent]

After trying out the make_docs.nu on the latest stuff in main, there does not seem to be any change to the table. It is still;

| input   | output |
| ------- | ------ |
| nothing | table  |

[raoulkent]

Found the reason; https://github.com/nushell/nushell/blob/c563e0cfb03aa465c813408290b2de103acc0bc7/crates/nu-engine/src/scope.rs#L187
Commenting this out, building and then running the make_docs.nu with the new build seems to work, producing a correct table that corresponds to the help cal information.

However, it's clear that this dedup was put there for a purpose, but it does break the docs generation in this case.

Certainly there is a lack of clarity within the docs if there are single input types that result in multiple output types.
On the other hand it's clear that you can with the flag get different results. Arguably the flag should be specified for these "extra" cases somehow.

Maybe;

input	output	flag
nothing	string
nothing	table	--as-table