Move command reference to navbar #782

Hofer-Julian · 2023-02-15T16:24:13Z

Move command reference to navbar
Create one sidebar entry for each category
Simplify javascript code

- Move command reference to navbar - Create sidebar entries for each category - Simplify javascript code

Hofer-Julian · 2023-02-15T16:26:43Z

The command reference is really long at the moment.
I feel that change makes it easier to consume.

fdncred · 2023-02-15T16:43:16Z

Thanks for this. It seems like a good change. I'm just not sure how to try it out. Is there an easy way to clone the repo and take it for a test drive?

Hofer-Julian · 2023-02-15T16:48:14Z

Thanks for this. It seems like a good change. I'm just not sure how to try it out. Is there an easy way to clone the repo and take it for a test drive?

You can checkout my branch and run npm run dev. That should serve the site locally.

If that doesn't work, then I can upload screenshots.

fdncred · 2023-02-15T16:57:19Z

ok, i just had to do npm install then npm dev run and it worked great! Thanks for the tip.

This makes the command reference much more usable. Great idea!
It makes me want to make sure our categories are more accurate and categorize things better.
The only thing that's a little weird is when you're drilling down to a command, you click that command, and it takes you to a different place. Now, if you want to go back to looking at the categories again, where you were previously, it's several clicks to get back there. I don't think this complaint should hold up the PR, but it may be worth thinking about in the future.
It makes me wonder if we can generate this automatically because it's pretty frequent that we add a category or move a command around. There's a bunch of those coming up in the next release and it makes me think this will be outdated in the next week.

Hofer-Julian · 2023-02-15T19:07:45Z

3. The only thing that's a little weird is when you're drilling down to a command, you click that command, and it takes you to a different place. Now, if you want to go back to looking at the categories again, where you were previously, it's several clicks to get back there. I don't think this complaint should hold up the PR, but it may be worth thinking about in the future.

Agreed, I am happy to move the commands to command-reference, adapt make_docs.nu and fix the links in a follow-up PR

4. It makes me wonder if we can generate this automatically because it's pretty frequent that we add a category or move a command around. There's a bunch of those coming up in the next release and it makes me think this will be outdated in the next week.

That is a good point, and that's also what I've tried first.
The main annoyance is that this way make_docs.nu would have to modify (generate?) sidebar/en.ts.
How would this then work with translations?
I am not sure.
Also, make_docs only works with re-runs on different platforms, which adds another level of complexity.

I've re-added the full command output to make sure that this PR at least isn't a regression.

hustcer · 2023-02-16T02:31:52Z

The command reference is really long at the moment. I feel that change makes it easier to consume.

Thanks, it's really an awesome change. I agree with that we should generate the command-references and nav items automatically:

For the command-references all the templates are quite similar to each other:

$> diff command-reference/bits.md command-reference/bytes.md
1c1
< # Bits
---
> # Bytes
10c10
<           .filter(p => p.frontmatter.categories.includes('bits'))
---
>           .filter(p => p.frontmatter.categories.includes('bytes'))

I think at least we can create all the templates automatically. A much better approach might be create a command reference layout or template just like .vuepress/components/BlogPosts.vue (I'm not quite sure if it's feasible, need more investigation)

For the nav items how about create a command nav js file by a script with the content like:

export const commandNavs = [
        'bits.md',
        'bytes.md',
        'conversions.md',
        'core.md',
        'database.md',
        'dataframe.md',
        'date.md',
        'default.md',
        'deprecated.md',
        'env.md',
        'experimental.md',
        'expression.md',
        'filesystem.md',
        'filters.md',
        'formats.md',
        'generators.md',
        'hash.md',
        'lazyframe.md',
        'math.md',
        'misc.md',
        'network.md',
        'platform.md',
        'random.md',
        'shells.md',
        'strings.md',
        'system.md',
        'viewers.md',
]

then we can import and use it in the sidebars

BTW: By running $nu.scope.commands|select category|uniq I got 30 categories, did we miss any of them? and how about merging category of lazyframe, dataframe and dataframe or lazyframe?

Hofer-Julian · 2023-02-16T08:42:28Z

I think at least we can create all the templates automatically. A much better approach might be create a command reference layout or template just like .vuepress/components/BlogPosts.vue (I'm not quite sure if it's feasible, need more investigation)

Creating the templates with a nu script sounds good to me.
For the Vue-specific approaches, I am afraid I don't know enough Vue to tackle that.

2. For the nav items how about create a command nav js file by a script with the content like:

export const commandNavs = [
        'bits.md',
        'bytes.md',
        'conversions.md',
        'core.md',
        'database.md',
        'dataframe.md',
        'date.md',
        'default.md',
        'deprecated.md',
        'env.md',
        'experimental.md',
        'expression.md',
        'filesystem.md',
        'filters.md',
        'formats.md',
        'generators.md',
        'hash.md',
        'lazyframe.md',
        'math.md',
        'misc.md',
        'network.md',
        'platform.md',
        'random.md',
        'shells.md',
        'strings.md',
        'system.md',
        'viewers.md',
]

then we can import and use it in the sidebars

That is a great idea.
This should also be relatively easy to generate with a nu script

3. BTW: By running `$nu.scope.commands|select category|uniq` I got 30 categories, did we miss any of them?

I've used help commands | get category | group-by | columns, and I think I didn't miss any (excluding dataframe or lazyframe as discussed below).
Can you name the specific categories you are missing?

And how about merging category of lazyframe, dataframe and dataframe or lazyframe?

I assume you mean on the Nushell side?
At least with dataframe or lazyframe, I also feel that category doesn't make too much sense.
The current implementation just ignores this category and appends its content to dataframe and lazyframe.

hustcer · 2023-02-16T09:55:12Z

Can you name the specific categories you are missing?

There are three categories: prompt(for gstat plugin), debug(maybe just added in v0.75.1? we can ignore it for now) and dataframe or lazyframe

And how about merging category of lazyframe, dataframe and dataframe or lazyframe?

I assume you mean on the Nushell side?

I mean on the docs side, I'm not sure whether we should do it on Nushell side or not.

At least with dataframe or lazyframe, I also feel that category doesn't make too much sense.
The current implementation just ignores this category and appends its content to dataframe and lazyframe.

Agree, that's why I think we should merge them in doc nav

Hofer-Julian · 2023-02-16T10:02:42Z

There are three categories: prompt(for gstat plugin), debug(maybe just added in v0.75.1? we can ignore it for now) and dataframe or lazyframe

I've installed Nushell with cargo install nu --features=dataframe.
Can you tell me what I have to do to get the other plugins?

I mean on the docs side, I'm not sure whether we should do it on Nushell side or not.

Not sure if generating categories and merging some of them is the best approach here.
In the current state, I could only easily merge them, because I've hard-coded the categories.

hustcer · 2023-02-16T10:21:06Z

I've installed Nushell with cargo install nu --features=dataframe.
Can you tell me what I have to do to get the other plugins?

You can clone the nushell repo and then run install-all.sh or install-all.ps1, then register gstat by register ~/.cargo/bin/nu_plugin_gstat

Hofer-Julian · 2023-02-16T10:33:23Z

Regarding this PR, I think what needs to be done is:

Add prompt category
Adapting make_docs.nu so that it generates:
- nav.ts file with categories used by sidebar/en.ts
- category markdown files in command-reference/categories
- command markdown files in command-reference/commands
Discussing on the Nushell side whether some categories should be refactored, especially dataframe or lazyframe

I have a preference for working on 2) in a follow-up PR, because I think this PR is already an improvement over the status quo.
However, I would be willing to extend this one too.

hustcer · 2023-02-16T11:09:24Z

command markdown files in command-reference/commands

I think we should keep the command docs in /book/commands/, unless you can search commands/ in **/*.md and modify all the affected links to avoid broken.

Hofer-Julian · 2023-02-16T11:12:07Z

command markdown files in command-reference/commands

I think we should keep the command docs in /book/commands/, unless you can search commands/ in **/*.md and modify all the affected links to avoid broken.

That's what I would have done, but I am also fine with leaving them where they are.

hustcer · 2023-02-16T11:16:31Z

Any option is acceptable, maybe move to command-reference/commands is a better choice if we won't add i18n support for commands' docs?

And do you think command-reference is a bit longer ? How about add commands/categories and make all commands placed in commands directly like commands/ls.md then https://www.nushell.sh/book/commands/ls.html will become https://www.nushell.sh/commands/ls.html, this will make the command url shorter. 😆

Hofer-Julian · 2023-02-16T14:08:44Z

And do you think command-reference is a bit longer ? How about add commands/categories and make all commands placed in commands directly like commands/ls.md then https://www.nushell.sh/book/commands/ls.html will become https://www.nushell.sh/commands/ls.html, this will make the command url shorter. 😆

Fine by me.
We can in general rename "Command Reference" to "Commands".
I was considering both and just took one of them at random.
What do you think @fdncred?

fdncred · 2023-02-16T14:11:53Z

@Hofer-Julian I like the suggestion. I also like Commands vs Command Reference.

Hofer-Julian · 2023-02-16T14:41:52Z

I've now added the prompt category and renamed command-reference to commands

2. Adapting `make_docs.nu` so that it generates:
   
   * `nav.ts` file with categories used by `sidebar/en.ts`
   * category markdown files in `command-reference/categories`
   * command markdown files in  `command-reference/commands`
I have a preference for working on 2) in a follow-up PR, because I think this PR is already an improvement over the status quo. However, I would be willing to extend this one too.

Any thoughts on this ☝️?

hustcer · 2023-02-16T15:04:50Z

Yeah, I think we can merge this one.

fdncred · 2023-02-16T15:50:09Z

LGTM!

This is some legwork to the CI - [x] fix one `get-row.nu` before 0.60, just because it was easy - [x] `modules/formats/to-ini.nu` - [x] `modules/git/git-v2.nu` - [x] `modules/git/git.nu` - [x] `modules/log/log.nu` - [x] `modules/weather/weatherdark.nu` - [x] `sourced/api_wrappers/worlframalpha.nu` - [x] `sourced/cool-oneliners/pwd-short.nu` - [x] `sourced/github/branch-protections/branch-protections.nu` - [x] `sourced/gitlab/gitlab.nu` - [x] `sourced/misc/nu_defs.nu` - [x] `sourced/update-path.nu` - [x] `sourced/webscraping/shell_starts.nu` I moved some auto-generated commands: - [x] `ack` - [x] `as` - [x] `curl` - [x] `fsarprc` - [x] `fsarpri` - [x] `godoc` - [x] `mysql` - [x] and `xgettext` to custom, so we keep the modifications. I had to comment some of the flags because the parser is not able to parse some flags. Those are explained in comments

Move command reference to navbar

5e323fa

- Move command reference to navbar - Create sidebar entries for each category - Simplify javascript code

Hofer-Julian marked this pull request as draft February 15, 2023 16:50

Hofer-Julian marked this pull request as ready for review February 15, 2023 16:51

Hofer-Julian added 2 commits February 15, 2023 20:13

Sort commands like nushell does

93af3e4

Add all commands to main page

d76f8e5

Hofer-Julian added 2 commits February 16, 2023 15:39

Rename command-reference to commands

01c7060

Add prompt category

58327d4

hustcer merged commit 9fe1d91 into nushell:main Feb 16, 2023

Hofer-Julian deleted the command-reference branch February 16, 2023 20:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Move command reference to navbar #782

Move command reference to navbar #782

Hofer-Julian commented Feb 15, 2023 •

edited

Loading

Hofer-Julian commented Feb 15, 2023

fdncred commented Feb 15, 2023

Hofer-Julian commented Feb 15, 2023

fdncred commented Feb 15, 2023 •

edited

Loading

Hofer-Julian commented Feb 15, 2023

hustcer commented Feb 16, 2023 •

edited

Loading

Hofer-Julian commented Feb 16, 2023

hustcer commented Feb 16, 2023

Hofer-Julian commented Feb 16, 2023

hustcer commented Feb 16, 2023 •

edited

Loading

Hofer-Julian commented Feb 16, 2023

hustcer commented Feb 16, 2023

Hofer-Julian commented Feb 16, 2023

hustcer commented Feb 16, 2023 •

edited

Loading

Hofer-Julian commented Feb 16, 2023

fdncred commented Feb 16, 2023

Hofer-Julian commented Feb 16, 2023

hustcer commented Feb 16, 2023

fdncred commented Feb 16, 2023

Move command reference to navbar #782

Move command reference to navbar #782

Conversation

Hofer-Julian commented Feb 15, 2023 • edited Loading

Hofer-Julian commented Feb 15, 2023

fdncred commented Feb 15, 2023

Hofer-Julian commented Feb 15, 2023

fdncred commented Feb 15, 2023 • edited Loading

Hofer-Julian commented Feb 15, 2023

hustcer commented Feb 16, 2023 • edited Loading

Hofer-Julian commented Feb 16, 2023

hustcer commented Feb 16, 2023

Hofer-Julian commented Feb 16, 2023

hustcer commented Feb 16, 2023 • edited Loading

Hofer-Julian commented Feb 16, 2023

hustcer commented Feb 16, 2023

Hofer-Julian commented Feb 16, 2023

hustcer commented Feb 16, 2023 • edited Loading

Hofer-Julian commented Feb 16, 2023

fdncred commented Feb 16, 2023

Hofer-Julian commented Feb 16, 2023

hustcer commented Feb 16, 2023

fdncred commented Feb 16, 2023

Hofer-Julian commented Feb 15, 2023 •

edited

Loading

fdncred commented Feb 15, 2023 •

edited

Loading

hustcer commented Feb 16, 2023 •

edited

Loading

hustcer commented Feb 16, 2023 •

edited

Loading

hustcer commented Feb 16, 2023 •

edited

Loading