Introduce help context #1484

Niloth-p · 2024-04-18T16:56:05Z

What does this PR do, and why?

Refactors set_footer_text() of core.py
Refactors lint_hotkeys heavily, in preparation for contexts.
Introduces context to track the current focus.
Uses context to generate relevant footer hints.
Demonstrates a Contextual Help Menu and "parent contexts".

Commit Grouping

Commits grouped by headings, and by another type Includes references for motivation of some groups.

Footer updates:

ui: Make the Help hotkey suggestion in the footer more conventional. (1)
refactor: ui/core/boxes: Separate out function to reset footer text. (2)
refactor: ui/core: Separate footer events from set_footer_text(). (2)
ui: Add state variable to track live footer events. (2)

Rewrite Lint-hotkeys: general improvements (3)

lint-hotkeys: Handle the doc file does not exist exception.
refactor: lint-hotkeys: Remove the write_hotkeys_file() function.
refactor: lint-hotkeys: Make the integer error flag boolean. (edited commit from Lint the validity of help categories #1518)
refactor: lint-hotkeys: Rewrite function docstrings and comments.
refactor: lint-hotkeys: Rename get_hotkeys_file_string().
refactor: lint-hotkeys: Rename ambiguous keyword "action" to "batch".
refactor: lint-hotkeys: Improve variable naming of generated dict.
lint-hotkeys: Refactor the flow by creating new ENTRY_BY_CATEGORIES.
refactor: lint-hotkeys: Delay generation of file string when linting.
refactor: lint-hotkeys: Split out the help text linting function.
refactor: lint-hotkeys: Split out the function that lints categories.
lint-hotkeys: Restructure the error messages of lint_help_text().
lint-hotkeys: Lint for typos in key_category values. (edited commit from Lint the validity of help categories #1518)

Refactor Lint-hotkeys: in preparation for linting contexts (3)

These commits share a common line at the bottom of their commit messages - "Part of adding generic variables in preparation for contexts."
Once reviewed, we could squash these commits.

refactor: lint-hotkeys: Use help_group instead of HELP_CATEGORIES.
refactor: lint-hotkeys: Create generic variable entries_by_group.
refactor: lint-hotkeys: Create generic variables for key_category.
refactor: lint-hotkeys: Replace 'category(ies)' with 'group(s)'.
refactor: lint-hotkeys: Delete constant OUTPUT_FILE_NAME, compute it.
refactor: lint-hotkeys: Replace usage of OUTPUT_FILE.

Inculcates the above commits.

refactor: lint-hotkeys: Generalize the traversal of key group values.
refactor: lint-hotkeys: Use bundled group values.

Adding contexts + linting:

keys: Add a contexts field to Key Binding. (3)
lint-hotkeys: Add argument to generate a keys file grouped by contexts. (3)

Use contexts in footer hint:

keys: Use the help contexts in generating random help tips.
keys: Include previously excluded random help hints.
ui: Enable footer texts to display contextual help tips. (2)
ui/keys: Display the context of the footer hint. (1)

Track context switching

contexts/core/ui: Track the currently focused widget in the UI.

Contextual Help Menu

core/ui/views/keys: Add a Contextual Help Menu. (4)

Parent Contexts

keys/views: Add mapping of contexts to broader contexts they belong to. (3)(4)

Another dimension of grouping of commits:

The commits/groups marked with the suffix number in brackets denotes commits related to the following groups:
(1) Footer Hint format
(2) commits related to set_footer_text()
(3) Linting commits
(4) Contextual Help Menu
(5) The contexts feature - all commits from the adding contexts part. The commits that do not depend on the contexts are obviously placed at the front, so all the commits after contexts have been introduced are all related to the contexts feature.

References: (corresponding to the numbered groups)

(1) See CZO topic: Improved UI design of footer hint
(2) Motivation for refactoring set_footer_text
(3) Motivation for lint-hotkeys refactoring commits, These commits also swallow the commits from Lint the validity of help categories #1518

Outstanding Aspects:

Miscellaneous aspects

Feedback needed on all the naming changes. There are a lot.

I've rebased several times to get the order of commits just right. Hope they are sensible. Can freely be squashed after reviewing.

The contexts.py is added in a separate file, although we could put it inside another file.
The logic flow is not very smooth (several if-else blocks), due to the differences in cases. Any suggestions on making it smoother would be helpful.

Tests have not been included for the context tracking.
Guidance required on framing the tests and the setup.

We primarily need to:

test the mapping of focus paths to widgets
simulate focus on a widget, test context update

But, I'm having trouble setting up the scenarios.

The Contextual Help Menu is merely added to test the contexts feature. It needs a lot more work before it's ready for a merge.

To view only the hints specific to a context, run ZT after setting HEAD to the penultimate commit
To view all working hints for a specific context, run ZT with the entire PR.

FAQ and Assumptions

FAQ:

Why bother this much with updating lint-hotkeys?

There was a feature in discussion - Rebinding/Remapping hotkeys, which require strong linting before users are allowed to customize their hotkeys.
Thus, refactoring lint-hotkeys is a necessity.

Why these many commits?

Since it's just a linting file, I was hoping we could get by with just the functionality, and not worry about the readability of the commits, as per my question here. But, it turns out linting is quite important for later features, so we do need this to be readable.
And since all the changes are done to the same file, we need to do them step by step to ensure readability, unlike changes made to different files which can easily be squashed (eg: see the Parent Contexts commit (the last one) that introduces parent contexts, adds linting and contextual help menu in the same step).
Any ideas for squashing while retaining readability are quite welcome. Or if I am holding high standards for what I consider readable, criticism is also welcome.

Why all commits in the same PR?

The earlier commits are motivated by the requirements of the later commits, and their implementation strongly depends (in the case of lint-hotkeys refactoring) on the implementation of the later commits.
The later commits can only be built on top of the earlier commits, so even if there were separate PRs, they'd need to be stacked, and merged in order.

Assumptions:

We want to generate the contexts.md file just for the devs and not the users.
Several commits for lint-hotkeys operate under this assumption.
Was unable to add an edited .gitignore with the contexts.md entry.
We want to start off with key_contexts instead of key_context.
Why not introduce this later? Because there are some obvious discrepancies, e.g., the toggle topics hint would only be able to mapped to either the stream list or the topic list.
See the context values for more such cases.

Follow-ups

Follow-ups:

[discuss] We currently allow the 'Tab' keypress to override any footer events. This can be controlled using the newly added variable that tracks live footer events.
[discuss] Allow opening the Help Menu from even within popups and editors.
[discuss] The design/formatting of the Contextual Help Menu
[discuss] Do we want to rename the fields key_category/key_context in the key bindings?
[discuss] I think that the testing function test_commands_for_random_tips() is quite overloaded. It is non-trivial and tests for several different things with very tight intersectional test cases:
- the working of "excluded_from_random_tips"
- usage of contexts
- single vs multiple contexts
- absence of context field
- no tips in given context
- the returned context value
Condition checks for vaildity of specific commands

External discussion & connections

Discussed in #zulip-terminal in Context Based Help Tips and Adding context to hotkeys
Fully fixes #
Partially fixes issue Make help hints context-dependent #515
Builds upon previous unmerged work in PR #
Is a follow-up to work in PR #
Requires merge of PR #
Merge will enable work on #

How did you test this?

Manually - Behavioral changes
Manually - Visual changes
Adapting existing automated tests
Adding automated tests for new behavior (or missing tests)
Existing automated tests should already cover this (only a refactor of tested code)

Niloth-p

There's a bunch of unfinished work here, and some significant changes to be made. I've mentioned the main ones in the CZO discussion.
I wanted to first ensure that I'm going in the right direction, so I've opened it up for review already.

zulipterminal/config/keys.py

tools/lint-hotkeys

neiljp

@Niloth-p There's a lot here!

I did give this a manual test, and many parts definitely seem to be working. I mainly moved around areas of the UI, and since some hotkeys (including just ?) effectively show a new random hint, it allows some degree of sampling of them.

I've not looked at the hotkeys assignment doc, since keys.py works fairly well in the first instance, and I'd started reading that before you added the feature :)

I've only left inline comments until prior to the specific context setting. That's partly since I'm wondering if there may be an alternative approach rather than setting it explicitly in many places. For example, you've already set the context depending on a focus path in a few places instead, and for popups this could be a class variable that is accessed by generic popup show code?

One helpful change would be to address the 'cycling' issue sooner rather than later, but even before or part of that we can improve the design slightly. The original design was to indicate that ? is general help, and show a random help next to it, but currently we have the help key right up next to Help and in parentheses rather than square brackets (which we now tend to use). There's also a colon rather than an indication that the general help is distinct from the hint. As an extension specific to this change, it'd be great to show the relevance of the hint - does it work in compose, stream list, selected message, etc. I could tell that it was displaying reasonable hints based on the context, but showing the context itself would be helpful for those less familiar :)

zulipterminal/config/keys.py

neiljp · 2024-04-19T06:16:09Z

zulipterminal/config/keys.py

    },
    'CYCLE_COMPOSE_FOCUS': {
        'keys': ['tab'],
        'help_text': 'Cycle through recipient and content boxes',
        'key_category': 'msg_compose',
+        'key_context': 'write_box',


As per another comment, using a user-facing name would be preferable for contexts.

This could be similar to the key_category, eg composing_message? Keeping names easily searchable (distinct from others) could be useful, so the same as key_category could be challenging if we want that.

zulipterminal/config/keys.py

zulipterminal/ui.py

tests/ui/test_ui.py

zulipterminal/ui.py

neiljp · 2024-04-26T00:14:09Z

I know you have lots of ideas and are getting code out well, but I'd suggest being cautious regarding pushing too far in one direction. It can be better to have work in another area to work on in parallel, rather than needing to heavily prune/drop/adjust a single direction if work in that one area takes a different path.

zulipbot · 2024-07-18T07:52:44Z

Hello @zulip/server-hotkeys, @zulip/server-refactoring members, this pull request was labeled with the "area: hotkeys", "area: refactoring" labels, so you may want to check it out!

rsashank

Wow, great PR @Niloth-p! It adds a much-needed functionality and is definitely the holy grail of your GSoC proposal. It’s fantastic to see it in action!

I left some comments, mostly minor changes and NITs. Functionally, it LGTM—I played around with it a bit and found that it recommends Esc to clear the search bar when you're in the users list, even if there's no search active. There might be a few outliers like that. Is it feasible to fix those on an individual scale? (That's the only one I’ve found so far, but I’ll let you know if I come across any others.)

tools/lint-hotkeys

rsashank · 2024-07-22T00:19:01Z

tools/lint-hotkeys

@@ -26,6 +26,23 @@ HELP_TEXT_STYLE = re.compile(r"^[a-zA-Z /()',&@#:_-]*$")
 KEYS_TO_EXCLUDE = ["q", "e", "m", "r", "Esc"]


+def read_help_categories() -> Dict[str, List[Tuple[str, List[str]]]]:


NIT: I feel we can squash this and the previous commit. The previous commit seems redundant since you're refactoring the flow and removing the function anyways.

refactor: lint-hotkeys: Improve variable naming of generated dict.
lint-hotkeys: Refactor the flow by creating new ENTRY_BY_CATEGORIES.

Ah, interesting, but we're not actually removing the function, it's just moved to the top to be placed before creating the new ENTRY_BY_CATEGORIES.

tools/lint-hotkeys

Changed the brackets used for the hotkey. Removed the colon.

Added function reset_footer_text() to reduce overloading of set_footer_text(), and updated its every usage. Updated tests.

By adding functions - set_footer_text_for_event() - set_footer_text_for_event_duration() and updating their usage. Updated tests.

To reduce redundancy in error messages for scenarios with several linting errors, collect all errors before printing them with the hint to resolve the errors. Also add a \n at the end of error messages.

Part of adding generic variables in preparation for contexts.

Replace 'key_category' with 'key_group' and 'key_group_value'. Add type KeyGroup to enforce typing. Part of adding generic variables in preparation for contexts.

This commit only updates the user-facing strings and variables, it does not update the occurrences in the comments or docstrings. Part of adding generic variables in preparation for contexts.

Part of adding generic variables in preparation for contexts.

Use CATEGORY_OUTPUT_FILE instead of the module constant OUTPUT_FILE. Use the smaller case 'output file' instead, in docstrings. Use existing_file as the name of the file object. Part of adding generic variables in preparation for contexts.

Convert string entries of `key_group` into lists, to later support the list of strings `key_contexts` with the same code.

Add a TypedDict bundling the values associated with category/context, and a dictionary mapping the group to its bundle. Pass group argument to all functions, to use the respective 'bundled' values associated with that group.

Add a dict of supported hotkey contexts for key bindings. Used a dict, instead of a list to facilitate the mapping of internal names to user-friendly names. Added TODO comments marking key bindings that require condition checks. Tests updated. Linting added.

Tests added and updated.

Hotkeys that used to be excluded because they were too specific, can now be useful as hints in particular contexts.

- Add a context property. - Update footer text on context changes, if a footer event is not already in progress. Tests added.

Return a valid display context name from commands_for_random_tips(), and use in the footer. Tests added and updated.

using a customized urwid.MainLoop. Added a new file contexts.py that implements the MainLoop that will track the context through the focus path. Developer overview document regenerated. Test updated.

Assigned an arbitrary hotkey. Will be overloaded onto the HELP command. Help Menus do not currently work from within editors or popups. Hotkeys document regenerated.

Niloth-p

Thank you for the testing it out and I appreciate the great suggestions, @rsashank!

recommends Esc to clear the search bar when you're in the users list, even if there's no search active

Yes, good spot. Those need some extra logic to handle. There are at least 3 key bindings of that sort that need condition checks, and for all of them, I'd attached a comment # TODO: condition check required at the bottom of their key bindings, until we come up with a smooth solution for handling them.

But, what I failed to consider was that since the comment is just for the devs, from the user POV, the hints would just seem bad hints.
So, I've currently turned off those key bindings from being used in random hints until the condition checks are added. Hope that's a good way of handling it.

Please do share any other observations as you come across them :)

Updates to the code:

Addressed Sashank's feedback, by adding the changes to the earlier commits and updating them gradually in sync with the changes in the later commits.
Rebased onto main, and added context field for the new OPEN_EXTERNAL_EDITOR command.

Niloth-p · 2024-07-18T04:44:14Z

zulipterminal/ui.py

@@ -104,13 +104,13 @@ def get_random_help(self) -> List[Any]:
        # Get random allowed hotkey (ie. eligible for being displayed as a tip)
        allowed_commands = commands_for_random_tips()
        if not allowed_commands:
-            return ["Help(?): "]
+            return ["Help[?] "]


Ideas on how we can further highlight the differentation of the Help and its hotkey from the random hint are welcome.

I'd suggest a space in the first instance? Then it'd be similar to eg. the Search [<key>] formatting we have right now. My other concern when running it is that we end up with

Help[?] OTHERKEY, KEY HELP TEXT FOR HINT

In that, the hint looks as close to the hint description as to the help hint, so we could add an extra space?

However, without that latter extra space, I'd still consider it an improvement, since the : is confusing by suggesting the Help is the hint, I think?

In the longer-term I mentioned highlighting hotkeys consistently, which might help here, but that's beyond the remit of this commit I think :)

Niloth-p · 2024-07-18T04:45:46Z

zulipterminal/config/keys.py

+    if len(random_tips) == 0:
+        return commands_for_random_tips("general")


This case has not been addressed in my update either. I'm not sure when we would have no hotkeys under the (now) "global" context. We will always have at least the Ctrl C hotkey, so it should be fine?

Niloth-p · 2024-07-18T06:54:35Z

tools/lint-hotkeys

 GroupedHelpEntries = Dict[str, List[Tuple[str, List[str]]]]


 def read_help_groups(key_group: KeyGroup) -> GroupedHelpEntries:
    """
    Generate a dict from KEYS_FILE
-    key: help category
-    value: a list of help texts and key combinations, for each key binding in that help category
+    key: help category/context


I've used the word "groups" for the variables.
But, mention category/context in all the docstrings.

I hope everyone's fine with calling categories & contexts with the common name groups 🤞, praying for fewer merge conflicts 😅

Niloth-p · 2024-07-22T07:03:05Z

tools/lint-hotkeys

@@ -26,6 +26,23 @@ HELP_TEXT_STYLE = re.compile(r"^[a-zA-Z /()',&@#:_-]*$")
 KEYS_TO_EXCLUDE = ["q", "e", "m", "r", "Esc"]


+def read_help_categories() -> Dict[str, List[Tuple[str, List[str]]]]:


Ah, interesting, but we're not actually removing the function, it's just moved to the top to be placed before creating the new ENTRY_BY_CATEGORIES.

tools/lint-hotkeys

Update the contextual help menu to use the parent contexts as well. Add linting for parent contexts mapping.

zulipbot · 2024-08-20T00:03:21Z

Heads up @Niloth-p, we just merged some commits that conflict with the changes you made in this pull request! You can review this repository's recent commits to see where the conflicts occur. Please rebase your feature branch against the upstream/main branch and resolve your pull request's merge conflicts accordingly.

neiljp

@Niloth-p I'm not sure if this was 34 commits before, but it certainly makes it challenging to review as it is - it can be intimidating just to see there are 34, at least ;) The commits aren't difficult to read in most cases, which helps 👍

I started focusing on the early commits, since they have potential for simple refactoring too (and that bug?). However, as per your current PR intro you then have over 10 commits for tidying the linter, presumably from the other previous PR, before then extending that to work to prepare for the contextual help.

So, I've focused this review on those earlier commits, then mostly towards the end, since the early part may be merged sooner and the latter might be simplified. Getting some commits merged will make this easier to handle!

The approach you're using for setting context does seem to work, but I see I mentioned the class variables idea before. What do you think?

neiljp · 2024-08-20T00:26:06Z

zulipterminal/ui.py

@@ -104,13 +104,13 @@ def get_random_help(self) -> List[Any]:
        # Get random allowed hotkey (ie. eligible for being displayed as a tip)
        allowed_commands = commands_for_random_tips()
        if not allowed_commands:
-            return ["Help(?): "]
+            return ["Help[?] "]


I'd suggest a space in the first instance? Then it'd be similar to eg. the Search [<key>] formatting we have right now. My other concern when running it is that we end up with

Help[?] OTHERKEY, KEY HELP TEXT FOR HINT

In that, the hint looks as close to the hint description as to the help hint, so we could add an extra space?

However, without that latter extra space, I'd still consider it an improvement, since the : is confusing by suggesting the Help is the hint, I think?

In the longer-term I mentioned highlighting hotkeys consistently, which might help here, but that's beyond the remit of this commit I think :)

neiljp · 2024-08-20T00:33:52Z

zulipterminal/ui.py

-            "Help(?): ",
+            "Help[?] ",


Looking at this method, it would be useful to refactor this common text at the same time?

neiljp · 2024-08-20T00:43:34Z

zulipterminal/ui.py

-        if duration is not None:
-            assert duration > 0
-            time.sleep(duration)
-            self.reset_footer_text()


Nit: This assert didn't make it across the refactor.

neiljp · 2024-08-20T00:51:40Z

zulipterminal/ui.py

    @asynch
-    def set_footer_text(
-        self,
-        text: List[Any],
-        style: str = "footer",
-        duration: Optional[float] = None,
-    ) -> None:
+    def set_footer_text(self, text: List[Any], style: str = "footer") -> None:


Does this function need to be @asynch now? Would delegating that simplify the problem we had?

neiljp · 2024-08-20T00:56:26Z

zulipterminal/ui.py

+    def set_footer_text_for_event(self, text: List[Any], style: str = "footer") -> None:
+        self.set_footer_text(text, style)
+
+    def set_footer_text_for_event_duration(
+        self, text: List[Any], duration: float, style: str = "footer"
+    ) -> None:


Just reading this, it's unclear to me what the 'event' refers to:

there's no context for why (most) calls now use a set_footer_text_for_event* variant

you add a non-'event' variant in the contextual-help commits (much) later

if there will be another variant name-wise, this would be a better rename much closer to that addition, otherwise it looks confusing among these commits

there are other calling points that don't use these names; should they? (see another comment)

neiljp · 2024-08-20T02:44:36Z

zulipterminal/contexts.py

+class FocusTrackingMainLoop(urwid.MainLoop):
+    def __init__(
+        self,
+        widget: urwid.Widget,
+        palette: ThemeSpec,
+        screen: Optional[urwid.BaseScreen],
+    ) -> None:
+        super().__init__(widget, palette, screen)
+        self.previous_focus_path = None
+        self.view = widget
+
+    def process_input(self, input: List[str]) -> None:
+        super().process_input(input)
+        self.track_focus_change()
+
+    def track_focus_change(self) -> None:


It does seem straightforward to track focus-change events via a derived class here, to ensure it is called after each input event 👍

However, while it may be due to the other complexity, I'm not clear if we need the rest of the code to explicitly be in the loop class?

neiljp · 2024-08-20T02:55:35Z

zulipterminal/config/keys.py

+PARENT_CONTEXTS: Dict[str, List[str]] = {
+    "global": [],
+    "general": ["global"],


I think this commit is interesting, but it seems to make the context help popup rather more confusing, perhaps due to the large number of general global keys.

Another point after looking at the 'path' code, is whether this would lose too much by being dynamic using the class constants? eg. if the path found various known terms, it could fetch help from them all?

neiljp · 2024-08-20T02:57:05Z

zulipterminal/ui_tools/views.py

-    def __init__(self, controller: Any, title: str) -> None:
+    def __init__(
+        self, controller: Any, title: str, context: Optional[str] = None
+    ) -> None:


This fails to toggle properly with contextual help.

neiljp · 2024-08-20T04:04:16Z

zulipterminal/ui.py

+    def set_footer_text_for_event_duration(
+        self, text: List[Any], duration: float, style: str = "footer"
+    ) -> None:
+        self.set_footer_text_for_event(text, style)
+        time.sleep(duration)
+        self.reset_footer_text()


This function is not asynch, so blocks for that duration. This breaks existing behavior. For example, try editing an old message that you cannot - the UI just stops updating, before catching up.

We shouldn't make everything asynch, as that puts everything in a thread and makes it a lot more complex, which was one benefit to the existing approach. However, this needs resolving.

neiljp · 2024-08-20T04:34:01Z

zulipterminal/ui.py

            ("footer_contrast", f" {random_command_display_keys} "),
-            f" {random_command['help_text']}",
+            f" ({tip_context}) ",
+            (
+                "footer_contrast",
+                f" {random_command['help_text']} ",
+            ),


This shows the information quite well at this stage 👍

Later, I can see we'll want to iterate on the layout - there's a similar issue as with the Help [?] point, but also that the context/keys/descriptions 'bounce around' spacing-wise.

zulipbot added the size: XL [Automatic label added by zulipbot] label Apr 18, 2024

Niloth-p force-pushed the 1484-introduce-help-context branch 3 times, most recently from 5b38003 to 0a1909c Compare April 24, 2024 17:34

Niloth-p marked this pull request as ready for review April 24, 2024 19:18

Niloth-p commented Apr 24, 2024

View reviewed changes

zulipterminal/config/keys.py Outdated Show resolved Hide resolved

tools/lint-hotkeys Show resolved Hide resolved

neiljp reviewed Apr 25, 2024

View reviewed changes

neiljp added the PR awaiting update PR has been reviewed & is awaiting update or response to reviewer feedback label Apr 26, 2024

This was referenced May 4, 2024

boxes/views: Adopt urwid_readline for all editors. #1492

Merged

Minor improvements in lint hotkeys #1482

Closed

This was referenced Jun 13, 2024

Add manual cycling of random hints in footer #1517

Merged

Create new help categories related to opening compose box #1520

Merged

Niloth-p force-pushed the 1484-introduce-help-context branch 4 times, most recently from 016ddf0 to e4d57a3 Compare July 18, 2024 07:50

Niloth-p added PR needs buddy review area: hotkeys area: refactoring area: popup: help and removed PR awaiting update PR has been reviewed & is awaiting update or response to reviewer feedback labels Jul 18, 2024

Niloth-p requested a review from rsashank July 18, 2024 07:52

rsashank reviewed Jul 22, 2024

View reviewed changes

rsashank added PR awaiting update PR has been reviewed & is awaiting update or response to reviewer feedback and removed PR needs buddy review labels Jul 22, 2024

Niloth-p added 3 commits July 22, 2024 11:23

ui: Make the Help hotkey suggestion in the footer more conventional.

de8d7a6

Changed the brackets used for the hotkey. Removed the colon.

refactor: ui/core/boxes: Separate out function to reset footer text.

9fccce3

Added function reset_footer_text() to reduce overloading of set_footer_text(), and updated its every usage. Updated tests.

refactor: ui/core: Separate footer events from set_footer_text().

13410a2

By adding functions - set_footer_text_for_event() - set_footer_text_for_event_duration() and updating their usage. Updated tests.

Niloth-p added 18 commits July 22, 2024 12:23

lint-hotkeys: Restructure the error messages of lint_help_text().

4e7a4f2

To reduce redundancy in error messages for scenarios with several linting errors, collect all errors before printing them with the hint to resolve the errors. Also add a \n at the end of error messages.

lint-hotkeys: Lint for typos in key_category values.

efc8f82

refactor: lint-hotkeys: Use help_group instead of HELP_CATEGORIES.

ac8e715

Part of adding generic variables in preparation for contexts.

refactor: lint-hotkeys: Create generic variable entries_by_group.

58ec337

Part of adding generic variables in preparation for contexts.

refactor: lint-hotkeys: Create generic variables for key_category.

3ce52db

Replace 'key_category' with 'key_group' and 'key_group_value'. Add type KeyGroup to enforce typing. Part of adding generic variables in preparation for contexts.

refactor: lint-hotkeys: Replace 'category(ies)' with 'group(s)'.

4911685

This commit only updates the user-facing strings and variables, it does not update the occurrences in the comments or docstrings. Part of adding generic variables in preparation for contexts.

refactor: lint-hotkeys: Delete constant OUTPUT_FILE_NAME, compute it.

b35e0ce

Part of adding generic variables in preparation for contexts.

refactor: lint-hotkeys: Generalize the traversal of key group values.

e2c7e57

Convert string entries of `key_group` into lists, to later support the list of strings `key_contexts` with the same code.

refactor: lint-hotkeys: Use bundled group values.

f908dc6

Add a TypedDict bundling the values associated with category/context, and a dictionary mapping the group to its bundle. Pass group argument to all functions, to use the respective 'bundled' values associated with that group.

lint-hotkeys: Add argument to generate a keys file grouped by contexts.

a8dd4de

keys: Use the help contexts in generating random help tips.

a76da7f

Tests added and updated.

keys: Include previously excluded random help hints.

9c48eb7

Hotkeys that used to be excluded because they were too specific, can now be useful as hints in particular contexts.

ui: Enable footer texts to display contextual help tips.

2e1b0f0

- Add a context property. - Update footer text on context changes, if a footer event is not already in progress. Tests added.

ui/keys: Display the context of the footer hint.

1b6ad6b

Return a valid display context name from commands_for_random_tips(), and use in the footer. Tests added and updated.

contexts/core/ui: Track the currently focused widget in the UI.

f75a309

using a customized urwid.MainLoop. Added a new file contexts.py that implements the MainLoop that will track the context through the focus path. Developer overview document regenerated. Test updated.

core/ui/views/keys: Add a Contextual Help Menu.

58b1a96

Assigned an arbitrary hotkey. Will be overloaded onto the HELP command. Help Menus do not currently work from within editors or popups. Hotkeys document regenerated.

Niloth-p force-pushed the 1484-introduce-help-context branch from e4d57a3 to e79f68b Compare July 22, 2024 07:02

Niloth-p commented Jul 22, 2024

View reviewed changes

keys/views: Add mapping of contexts to broader contexts they belong to.

3513d73

Update the contextual help menu to use the parent contexts as well. Add linting for parent contexts mapping.

Niloth-p force-pushed the 1484-introduce-help-context branch from e79f68b to 3513d73 Compare July 22, 2024 09:03

Niloth-p mentioned this pull request Jul 22, 2024

Lint the validity of help categories #1518

Open

18 tasks

Niloth-p added PR needs mentor review and removed PR awaiting update PR has been reviewed & is awaiting update or response to reviewer feedback labels Jul 22, 2024

Niloth-p requested a review from zormit July 22, 2024 10:48

zulipbot added the has conflicts label Aug 20, 2024

neiljp reviewed Aug 20, 2024

View reviewed changes

neiljp added the PR awaiting update PR has been reviewed & is awaiting update or response to reviewer feedback label Aug 20, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduce help context #1484

Introduce help context #1484

Niloth-p commented Apr 18, 2024 •

edited

Loading

Niloth-p left a comment

neiljp left a comment

neiljp Apr 19, 2024

neiljp commented Apr 26, 2024

zulipbot commented Jul 18, 2024

rsashank left a comment

rsashank Jul 22, 2024

Niloth-p Jul 22, 2024

Niloth-p left a comment

Niloth-p Jul 18, 2024

neiljp Aug 20, 2024

Niloth-p Jul 18, 2024

Niloth-p Jul 18, 2024

Niloth-p Jul 22, 2024

zulipbot commented Aug 20, 2024

neiljp left a comment

neiljp Aug 20, 2024

neiljp Aug 20, 2024

neiljp Aug 20, 2024

neiljp Aug 20, 2024

neiljp Aug 20, 2024

neiljp Aug 20, 2024

neiljp Aug 20, 2024

neiljp Aug 20, 2024

neiljp Aug 20, 2024

neiljp Aug 20, 2024

		@@ -26,6 +26,23 @@ HELP_TEXT_STYLE = re.compile(r"^[a-zA-Z /()',&@#:_-]*$")
		KEYS_TO_EXCLUDE = ["q", "e", "m", "r", "Esc"]


		def read_help_categories() -> Dict[str, List[Tuple[str, List[str]]]]:

		if len(random_tips) == 0:
		return commands_for_random_tips("general")

Introduce help context #1484

Are you sure you want to change the base?

Introduce help context #1484

Conversation

Niloth-p commented Apr 18, 2024 • edited Loading

What does this PR do, and why?

Commit Grouping

Footer updates:

Rewrite Lint-hotkeys: general improvements (3)

Refactor Lint-hotkeys: in preparation for linting contexts (3)

Adding contexts + linting:

Use contexts in footer hint:

Track context switching

Contextual Help Menu

Parent Contexts

Another dimension of grouping of commits:

References: (corresponding to the numbered groups)

Outstanding Aspects:

FAQ:

Assumptions:

Follow-ups:

External discussion & connections

How did you test this?

Niloth-p left a comment

Choose a reason for hiding this comment

neiljp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

neiljp commented Apr 26, 2024

zulipbot commented Jul 18, 2024

rsashank left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Niloth-p left a comment

Choose a reason for hiding this comment

Updates to the code:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

zulipbot commented Aug 20, 2024

neiljp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Niloth-p commented Apr 18, 2024 •

edited

Loading