Repository: zulip/zulip-terminal
Pull request #1283 (2023-01-07 03:31:03)

Improve documentation of zuliprc as used by zulip-term
<!-- Please see https://github.com/zulip/zulip-terminal#contributor-guidelines ! -->

**What does this PR do?**  <!-- Overall description goes here -->

This is motivated by #**zulip-terminal > zuliprc template in README** (Summer 2021), as well as #1269 recently - namely that the zterm configuration section of the zuliprc used by ZT as documented in the README could be improved and more cleanly defined/annotated.

In particular, the above discussion and issue relate to where both footlinks and maximum-footlinks options are present (uncommented) in a zuliprc file at the same time, which `zulip-term` knows are incompatible - and so outputs a rather terse error message.

This PR approaches this on two fronts, as two commits:
- improve the example zuliprc file in the README, such that the zterm settings relate to default values that both fundamentally work if copy/pasted, and are better documented
- adjust the error messages related to footlinks, to ensure that if this does occur in future, that the source of the issue should be clearer to the user

**Tested?** <!-- Fine to leave some of these unchecked if this is a draft/work-in-progress -->
- [x] Manually
- [x] Existing tests (adapted, if necessary)
- [ ] New tests added (for any new behavior)
- [x] Passed linting & tests (each commit)
<!-- Code must pass CI (GitHub Actions) before merging - look for the green tick! -->


Patch:
diff --git a/README.md b/README.md
index e3bed8e..25b1b48 100644
--- a/README.md
+++ b/README.md
@@ -128,30 +128,41 @@ We suggest running `zulip-term` using the `-e` or `--explore` option (in explore
 
 ## Configuration
 
-The `zuliprc` file contains information to connect to your chat server in the `[api]` section, but also optional configuration for `zulip-term` in the `[zterm]` section:
-
+The `zuliprc` file contains two sections:
+- an `[api]` section with information required to connect to your Zulip server
+- a `[zterm]` section with configuration specific to `zulip-term`
+
+A file with only the first section can be auto-generated in some cases by
+`zulip-term`, or you can download one from your account on your server (see
+above). Parts of the second section can be added and adjusted in stages when
+you wish to customize the behavior of `zulip-term`.
+
+The example below, with dummy `[api]` section contents, represents a working
+configuration file with all the default compatible `[zterm]` values uncommented
+and with accompanying notes:
 ```
 [api]
 email=example@example.com
 key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-site=https://realm.zulipchat.com
+site=https://example.zulipchat.com
 
 [zterm]
-# Alternative themes are listed in the FAQ
+## Theme: available themes can be found by running `zulip-term --list-themes`, or in docs/FAQ.md
 theme=zt_dark
-# Autohide defaults to 'no_autohide', but can be set to 'autohide' to hide the left & right panels except when focused.
-autohide=autohide
-# Footlinks default to 'enabled', but can be set to 'disabled' to hide footlinks.
-# disabled won't show any footlinks.
-# enabled will show the first 3 per message.
-footlinks=disabled
-# If you need more flexibility, use maximum-footlinks.
-# Maximum footlinks to be shown, defaults to 3, but can be set to any value 0 or greater.
-# This option cannot be used with the footlinks option; use one or the other.
-maximum-footlinks=3
-# Notify defaults to 'disabled', but can be set to 'enabled' to display notifications (see next section).
-notify=enabled
-# Color depth defaults to 256 colors, but can be set to 1 (for monochrome), 16, or 24bit.
+
+## Autohide: set to 'autohide' to hide the left & right panels except when they're focused
+autohide=no_autohide
+
+## Footlinks: set to 'disabled' to hide footlinks; 'enabled' will show the first 3 per message
+## For more flexibility, comment-out this value, and un-comment maximum-footlinks below
+footlinks=enabled
+## Maximum-footlinks: set to any value 0 or greater, to limit footlinks shown per message
+# maximum-footlinks=3
+
+## Notify: set to 'enabled' to display notifications (see elsewhere for configuration notes)
+notify=disabled
+
+## Color-depth: set to one of 1 (for monochrome), 16, 256, or 24bit
 color-depth=256
 ```
 
diff --git a/zulipterminal/cli/run.py b/zulipterminal/cli/run.py
index f7c7f77..25343dd 100755
--- a/zulipterminal/cli/run.py
+++ b/zulipterminal/cli/run.py
@@ -396,14 +396,18 @@ def main(options: Optional[List[str]] = None) -> None:
             and zterm["maximum-footlinks"][1] == ZULIPRC_CONFIG
         ):
             exit_with_error(
-                "Footlinks property is not allowed alongside maximum-footlinks"
+                "Configuration Error: "
+                "footlinks and maximum-footlinks options cannot be used together"
             )
 
-        if (
-            zterm["maximum-footlinks"][1] == ZULIPRC_CONFIG
-            and int(zterm["maximum-footlinks"][0]) < 0
-        ):
-            exit_with_error("Minimum value allowed for maximum-footlinks is 0")
+        if zterm["maximum-footlinks"][1] == ZULIPRC_CONFIG:
+            maximum_footlinks = int(zterm["maximum-footlinks"][0])
+            if maximum_footlinks < 0:
+                exit_with_error(
+                    "Configuration Error: "
+                    "Minimum value allowed for maximum-footlinks is 0; "
+                    f"you used '{maximum_footlinks}'"
+                )
 
         if zterm["footlinks"][1] == ZULIPRC_CONFIG:
             if zterm["footlinks"][0] == DEFAULT_SETTINGS["footlinks"]:


Test patch:
diff --git a/tests/cli/test_run.py b/tests/cli/test_run.py
index 1452cfd..0cece4c 100644
--- a/tests/cli/test_run.py
+++ b/tests/cli/test_run.py
@@ -410,11 +410,11 @@ def test_successful_main_function_with_config(
     [
         (
             {"footlinks": "enabled", "maximum-footlinks": "3"},
-            "Footlinks property is not allowed alongside maximum-footlinks",
+            "Configuration Error: footlinks and maximum-footlinks options cannot be used together",
         ),
         (
             {"maximum-footlinks": "-3"},
-            "Minimum value allowed for maximum-footlinks is 0",
+            "Configuration Error: Minimum value allowed for maximum-footlinks is 0; you used '-3'",
         ),
     ],
 )