help: Add a keyword feature #4630

Grillo-0 · 2024-10-13T03:04:36Z

It would be nice to not need to go the documentation website. This aims to solve that by introducing the concept of categories to the help command.

Basically, categories are things that we want to add help messages to, but they don't necessarily have an associated subcommand.

For now we only have two categories:
- revsets: Shows the docs for revsets
- tutorial: Shows the tutorial that is on the documentation

You get the category content by tipping jj help revsets.

It would be nice to have all the documentation on the categories, maybe a next commit could do it.

Checklist

If applicable:

I have updated CHANGELOG.md
I have updated the documentation (README.md, docs/, demos/)
I have updated the config schema (cli/src/config-schema.json)
I have added tests to cover my changes

joyously · 2024-10-13T04:07:15Z

Is this associated with #3224?

cli/src/commands/help.rs

Grillo-0 · 2024-10-13T12:33:30Z

Is this associated with #3224?

Oh! I didn't know about that! But yeah, I don't see why this couldn't be extended after to explain errors. This PR started from discussion on #4518: #4518 (comment).

cli/src/commands/help.rs

cli/tests/test_help_command.rs

cli/src/commands/help.rs

cli/tests/test_help_command.rs

thoughtpolice · 2024-10-15T03:24:22Z

Related: #3130 by me, which actually adds a docs subcommand that just includes all documentation from the website into the binary; it uses a terminal display library to make the markdown more readable. But I haven't had any time to really polish it and make it merge worthy.

I don't think it should block this or anything, just putting it out there. In the future I imagine some merger of these two ideas would occur, really.

cli/src/commands/help.rs

martinvonz · 2024-10-30T04:58:59Z

@Grillo-0: I see that you requested my review. I find it hard to find enough time to review many PRs lately. I'm happy to trust Yuya's review. Let me know if you really want me to review it too.

cli/src/command_error.rs

cli/src/commands/help.rs

cli/tests/test_help_command.rs

cli/src/commands/help.rs

yuja

Thanks.

CHANGELOG.md

It would be nice to not need to go the documentation website. This aims to solve that by introducing the concept of keyword to the help command. Basically, keywords are things that we want to add help messages to, but they don't necessarily have an associated subcommand. For now we only have two keywords: - `revsets`: Shows the docs for revsets - `tutorial`: Shows the tutorial that is on the documentation You get the keyword content by tipping `jj help --keyword revsets` or `jj help -k revsets`. You can also list the available keywords with `jj help --help`. It would be nice to have all the documentation on the keywords, maybe a next commit could do it.

Grillo-0 · 2024-10-31T16:01:01Z

I will merge this

martinvonz · 2024-11-05T01:31:20Z

cli/src/commands/help.rs

+    Keyword {
+        name: "revsets",
+        description: "A functional language for selecting a set of revision",
+        content: include_str!("../../../docs/revsets.md"),


Does anyone know if this pointer outside of the crate will work when we publish to crates.io (as I'm supposed to do on wednesday)?

Good catch. It could be worked around by a symlink (ln -s ../docs cli), but symlink has its own problem, so I have no idea.

I somewhat doubt it will, I found a rather confusing thread about it.

We should probably instead use build.rs in order to get access to OUT_DIR and just copy the files there at compile time. A minor annoyance but nothing too horrid, I guess (though I'd need to figure out how to port the Buck changes, I expect it would be very minor.)

Do you mean that we should make build.rs copy the files from docs/ into e.g. cli/srcs/docs/ so we have two copies of the files?

Perhaps, what we can do with build.rs is to fall back to ../docs if ./docs doesn't exist? We'll need docs symlink or something in order to include docs/* in the release package.

Grillo-0 requested review from yuja and martinvonz October 13, 2024 03:04

Grillo-0 force-pushed the help-category branch from ef49089 to 7024fe6 Compare October 13, 2024 03:15

yuja reviewed Oct 13, 2024

View reviewed changes

cli/src/commands/help.rs Outdated Show resolved Hide resolved

cli/src/commands/help.rs Outdated Show resolved Hide resolved

cli/src/commands/help.rs Outdated Show resolved Hide resolved

Grillo-0 force-pushed the help-category branch 5 times, most recently from a173a66 to 60a048d Compare October 13, 2024 15:51

yuja reviewed Oct 14, 2024

View reviewed changes

joyously reviewed Oct 14, 2024

View reviewed changes

cli/src/commands/help.rs Outdated Show resolved Hide resolved

joyously reviewed Oct 14, 2024

View reviewed changes

cli/tests/test_help_command.rs Outdated Show resolved Hide resolved

joyously reviewed Oct 14, 2024

View reviewed changes

cli/tests/test_help_command.rs Outdated Show resolved Hide resolved

Grillo-0 force-pushed the help-category branch 5 times, most recently from a6ddaa7 to fd411fe Compare October 16, 2024 03:04

martinvonz reviewed Oct 16, 2024

View reviewed changes

cli/src/commands/help.rs Outdated Show resolved Hide resolved

Grillo-0 force-pushed the help-category branch from fd411fe to 01830bb Compare October 17, 2024 04:21

martinvonz reviewed Oct 18, 2024

View reviewed changes

cli/src/commands/help.rs Outdated Show resolved Hide resolved

Grillo-0 force-pushed the help-category branch 5 times, most recently from abe4799 to 24b84f3 Compare October 20, 2024 14:40

Grillo-0 requested a review from yuja October 20, 2024 15:22

Grillo-0 force-pushed the help-category branch 2 times, most recently from 595952a to 4312362 Compare October 26, 2024 21:37

Grillo-0 requested review from yuja, joyously and emilazy October 26, 2024 21:38

Grillo-0 force-pushed the help-category branch from 4312362 to 16882a2 Compare October 26, 2024 21:48

yuja reviewed Oct 27, 2024

View reviewed changes

cli/src/commands/help.rs Outdated Show resolved Hide resolved

cli/src/commands/help.rs Outdated Show resolved Hide resolved

cli/src/commands/help.rs Show resolved Hide resolved

Grillo-0 force-pushed the help-category branch 7 times, most recently from 3b8cba1 to cf590c5 Compare October 29, 2024 14:18

yuja reviewed Oct 30, 2024

View reviewed changes

Grillo-0 force-pushed the help-category branch 4 times, most recently from 59073e9 to cf61214 Compare October 30, 2024 14:24

Grillo-0 requested a review from yuja October 30, 2024 14:33

yuja approved these changes Oct 30, 2024

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

Grillo-0 force-pushed the help-category branch from cf61214 to 4306d04 Compare October 31, 2024 15:40

Grillo-0 merged commit f2acb98 into martinvonz:main Oct 31, 2024
18 checks passed

Grillo-0 deleted the help-category branch October 31, 2024 19:55

Grillo-0 mentioned this pull request Nov 1, 2024

Accept early args after help command #4518

Merged

4 tasks

martinvonz reviewed Nov 5, 2024

View reviewed changes

thoughtpolice mentioned this pull request Nov 5, 2024

build: fix cargo publish by symlinking cli/docs->docs #4773

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

help: Add a keyword feature #4630

help: Add a keyword feature #4630

Grillo-0 commented Oct 13, 2024 •

edited

Loading

joyously commented Oct 13, 2024

Grillo-0 commented Oct 13, 2024

thoughtpolice commented Oct 15, 2024

martinvonz commented Oct 30, 2024

yuja left a comment

Grillo-0 commented Oct 31, 2024

martinvonz Nov 5, 2024

yuja Nov 5, 2024

thoughtpolice Nov 5, 2024 •

edited

Loading

martinvonz Nov 5, 2024

yuja Nov 5, 2024

help: Add a keyword feature #4630

help: Add a keyword feature #4630

Conversation

Grillo-0 commented Oct 13, 2024 • edited Loading

Checklist

joyously commented Oct 13, 2024

Grillo-0 commented Oct 13, 2024

thoughtpolice commented Oct 15, 2024

martinvonz commented Oct 30, 2024

yuja left a comment

Choose a reason for hiding this comment

Grillo-0 commented Oct 31, 2024

martinvonz Nov 5, 2024

Choose a reason for hiding this comment

yuja Nov 5, 2024

Choose a reason for hiding this comment

thoughtpolice Nov 5, 2024 • edited Loading

Choose a reason for hiding this comment

martinvonz Nov 5, 2024

Choose a reason for hiding this comment

yuja Nov 5, 2024

Choose a reason for hiding this comment

Grillo-0 commented Oct 13, 2024 •

edited

Loading

thoughtpolice Nov 5, 2024 •

edited

Loading