From 64a202a12530fd641fc6a3b1d22720876c516f49 Mon Sep 17 00:00:00 2001 From: pagedown Date: Wed, 24 Aug 2022 13:26:50 +0800 Subject: [PATCH 1/7] Docs: Using the lowercase form of the key name consistently --- kitty/boss.py | 2 +- kitty/window.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/kitty/boss.py b/kitty/boss.py index 5db05e655..cc433c955 100644 --- a/kitty/boss.py +++ b/kitty/boss.py @@ -561,7 +561,7 @@ class Boss: For example:: - map F1 remote_control set-spacing margin=30 + map f1 remote_control set-spacing margin=30 See :ref:`rc_mapping` for details. ''') diff --git a/kitty/window.py b/kitty/window.py index b797db4c8..cf72414f0 100644 --- a/kitty/window.py +++ b/kitty/window.py @@ -1665,7 +1665,7 @@ class Window: For example:: - map F1 signal_child SIGTERM + map f1 signal_child SIGTERM ''') def signal_child(self, *signals: int) -> None: pid = self.child.pid_for_cwd @@ -1679,9 +1679,9 @@ class Window: For example:: # show the config docs - map F1 show_kitty_doc conf + map f1 show_kitty_doc conf # show the ssh kitten docs - map F1 show_kitty_doc kittens/ssh + map f1 show_kitty_doc kittens/ssh ''') def show_kitty_doc(self, which: str = '') -> None: url = docs_url(which) From 0e0578ff49d11a7929a88563d6ab342b4499beb6 Mon Sep 17 00:00:00 2001 From: pagedown Date: Wed, 24 Aug 2022 13:27:06 +0800 Subject: [PATCH 2/7] Docs: Use --help long option name in the document Remove the extra empty line in the CLI help for `--replay-commands`. --- docs/remote-control.rst | 2 +- kitty/cli.py | 1 - kitty/options/definition.py | 2 +- 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/remote-control.rst b/docs/remote-control.rst index 4eeca0db2..16410d51e 100644 --- a/docs/remote-control.rst +++ b/docs/remote-control.rst @@ -193,7 +193,7 @@ The :opt:`remote_control_password` can be specified multiple times to create different passwords with different capabilities. Run the following to get a list of all action names:: - kitty @ -h + kitty @ --help You can even use glob patterns to match action names, for example: diff --git a/kitty/cli.py b/kitty/cli.py index 39e98ad1e..0714029a1 100644 --- a/kitty/cli.py +++ b/kitty/cli.py @@ -779,7 +779,6 @@ Output commands received from child process to STDOUT. Replay previously dumped commands. Specify the path to a dump file previously created by :option:`{appname} --dump-commands`. You can open a new kitty window to replay the commands with:: - {appname} sh -c "{appname} --replay-commands /path/to/dump/file; read" diff --git a/kitty/options/definition.py b/kitty/options/definition.py index 6c5a5c486..4e7118c4b 100644 --- a/kitty/options/definition.py +++ b/kitty/options/definition.py @@ -2711,7 +2711,7 @@ Glob patterns can be used too, for example:: To get a list of available actions, run:: - kitty @ -h + kitty @ --help A set of actions to be allowed when no password is sent can be specified by using an empty password, for example:: From c437a367944008a712d6865b61a43a7ec9d017bb Mon Sep 17 00:00:00 2001 From: pagedown Date: Wed, 24 Aug 2022 13:27:12 +0800 Subject: [PATCH 3/7] Fix GitHub links in commented configuration Hyperlink GitHub related text roles: iss, pull, disc --- docs/extract-rst-targets.py | 2 +- kitty/cli.py | 15 +++++++++++++++ kitty/conf/types.py | 36 ++++++++++++++++++++++++------------ 3 files changed, 40 insertions(+), 13 deletions(-) diff --git a/docs/extract-rst-targets.py b/docs/extract-rst-targets.py index 41b39d897..cff2afc5b 100755 --- a/docs/extract-rst-targets.py +++ b/docs/extract-rst-targets.py @@ -14,7 +14,7 @@ def find_explicit_targets(text: str) -> Iterator[str]: def main() -> Dict[str, str]: - refs = {'github_discussions': 'https://github.com/kovidgoyal/kitty/discussions'} + refs = {} base = os.path.dirname(os.path.abspath(__file__)) for dirpath, dirnames, filenames in os.walk(base): if 'generated' in dirnames: diff --git a/kitty/cli.py b/kitty/cli.py index 0714029a1..8eae079e2 100644 --- a/kitty/cli.py +++ b/kitty/cli.py @@ -193,6 +193,21 @@ def ac(x: str) -> str: return ref_hyperlink(x, 'action-') +@role +def iss(x: str) -> str: + return ref_hyperlink(x, 'github-issue-') + + +@role +def pull(x: str) -> str: + return ref_hyperlink(x, 'github-pr-') + + +@role +def disc(x: str) -> str: + return ref_hyperlink(x, 'github-discussion-') + + OptionSpecSeq = List[Union[str, OptionDict]] diff --git a/kitty/conf/types.py b/kitty/conf/types.py index 31fb480c1..3a7a62955 100644 --- a/kitty/conf/types.py +++ b/kitty/conf/types.py @@ -72,7 +72,18 @@ def resolve_ref(ref: str, website_url: Callable[[str], str] = website_url) -> st href = f'actions/#{frag}' elif ref.startswith('term-') or ref.startswith('envvar-'): href = 'glossary/#' + ref - return website_url(href) + elif ref.startswith('github-'): + href = 'https://github.com/kovidgoyal/kitty' + parts = ref.split('-') + if parts[1] == 'issue': + href = f'{href}/issues/{parts[2]}' + elif parts[1] == 'pr': + href = f'{href}/pull/{parts[2]}' + elif parts[1] == 'discussion': + href = f'{href}/discussions/{parts[2]}' + if not (href.startswith('https://') or href.startswith('http://')): + href = website_url(href) + return href def remove_markup(text: str) -> str: @@ -84,27 +95,28 @@ def remove_markup(text: str) -> str: return t, q def sub(m: 'Match[str]') -> str: - if m.group(1) == 'ref': + if m.group(1) in ('ref', 'iss', 'pull', 'disc'): t, q = extract(m) + if m.group(1) == 'iss': + q = f'github-issue-{q}' + elif m.group(1) == 'pull': + q = f'github-pr-{q}' + elif m.group(1) == 'disc': + q = f'github-discussion-{q}' url = resolve_ref(q) if not url: - raise KeyError(f'Failed to resolve :ref: {q}') + raise KeyError(f'Failed to resolve :{m.group(1)}: {q}') return f'{t} <{url}>' if m.group(1) == 'doc': t, q = extract(m) return f'{t} <{website_url(q.lstrip("/"))}>' - if m.group(1) == 'ac': - q = m.group(2).split('<')[-1].rstrip('>') - return q - if m.group(1) == 'term': + if m.group(1) in ('term', 'option'): t, _ = extract(m) return t - if m.group(1) == 'option': - t, _ = extract(m) - return t - if m.group(1) == 'disc': + if m.group(1) in ('ac', 'opt'): t, q = extract(m) - return f'{t} {resolve_ref("github_discussions")}/{q}' + return f'{t} {q}' if q and q != t else t + return str(m.group(2)) return re.sub(r':([a-zA-Z0-9]+):`(.+?)`', sub, text, flags=re.DOTALL) From 9a70709bba8a52a76c7647a6ddaf02ceaa3db8e5 Mon Sep 17 00:00:00 2001 From: pagedown Date: Wed, 24 Aug 2022 13:27:19 +0800 Subject: [PATCH 4/7] Shorten the reference link to the top of the page Reduce the length of the link :ref:`shell_integration` in commented conf. --- docs/extract-rst-targets.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/extract-rst-targets.py b/docs/extract-rst-targets.py index cff2afc5b..b349eb385 100755 --- a/docs/extract-rst-targets.py +++ b/docs/extract-rst-targets.py @@ -25,7 +25,17 @@ def main() -> Dict[str, str]: raw = stream.read() href = os.path.relpath(stream.name, base).replace(os.sep, '/') href = href.rpartition('.')[0] + '/' + first_line = raw.lstrip('\n').partition('\n')[0] + first_target_added = False for explicit_target in find_explicit_targets(raw): + # Shorten the reference link to the top of the page. + # Note that anchor links should still be used in HTML docs + # to allow jumping within the same page. + if not first_target_added: + first_target_added = True + if first_line.startswith(f'.. _{explicit_target}:'): + refs[explicit_target] = href + continue refs[explicit_target] = href + f'#{explicit_target.replace("_", "-")}' return {'ref': refs} From ba9afc61a4df8a97ffb101087510dcd1b19511a4 Mon Sep 17 00:00:00 2001 From: pagedown Date: Wed, 24 Aug 2022 13:29:07 +0800 Subject: [PATCH 5/7] Hyperlink doc text role --- kitty/cli.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/kitty/cli.py b/kitty/cli.py index 8eae079e2..cbf7ce963 100644 --- a/kitty/cli.py +++ b/kitty/cli.py @@ -168,7 +168,9 @@ def file(x: str) -> str: @role def doc(x: str) -> str: - return website_url(x) + t, q = text_and_target(x) + url = f'kitty+doc://{hostname()}/{q.lstrip("/")}' + return hyperlink_for_url(url, t) @run_once From fd4a682c5bc2d4ec59daee9685b8fca21e02cf08 Mon Sep 17 00:00:00 2001 From: pagedown Date: Wed, 24 Aug 2022 13:29:51 +0800 Subject: [PATCH 6/7] Fix doc website URL with duplicate slashes --- kitty/conf/types.py | 2 +- kitty/constants.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/kitty/conf/types.py b/kitty/conf/types.py index 3a7a62955..5b89005df 100644 --- a/kitty/conf/types.py +++ b/kitty/conf/types.py @@ -109,7 +109,7 @@ def remove_markup(text: str) -> str: return f'{t} <{url}>' if m.group(1) == 'doc': t, q = extract(m) - return f'{t} <{website_url(q.lstrip("/"))}>' + return f'{t} <{website_url(q)}>' if m.group(1) in ('term', 'option'): t, _ = extract(m) return t diff --git a/kitty/constants.py b/kitty/constants.py index 521c22cf5..d1f9a2318 100644 --- a/kitty/constants.py +++ b/kitty/constants.py @@ -237,7 +237,7 @@ def website_url(doc_name: str = '', website: str = 'https://sw.kovidgoyal.net/ki if base: base += '/' doc_name = base + (f'#{frag}' if frag else '') - return website + doc_name + return website + doc_name.lstrip('/') handled_signals: Set[int] = set() From 7f228bcbf567ce4eb621bb348bf927ed5eb5375f Mon Sep 17 00:00:00 2001 From: pagedown Date: Wed, 24 Aug 2022 13:30:52 +0800 Subject: [PATCH 7/7] Docs: Unify the list style of available values Highlight the value and provide hyperlink in the description. --- kitty/launch.py | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/kitty/launch.py b/kitty/launch.py index a2bb72203..f3cec3499 100644 --- a/kitty/launch.py +++ b/kitty/launch.py @@ -59,24 +59,24 @@ default=window choices=window,tab,os-window,overlay,background,clipboard,primary Where to launch the child process: -:term:`window` - a new :term:`window` in the current tab, +:code:`window` + A new :term:`kitty window ` in the current tab -:term:`tab` - a new tab in the current :term:`OS Window ` +:code:`tab` + A new :term:`tab` in the current OS window -:term:`os-window ` - a new operating system window +:code:`os-window ` + A new :term:`operating system window ` -:term:`overlay` - an overlay window covering the current active window. +:code:`overlay` + An :term:`overlay window ` covering the current active kitty window -:italic:`background` - the process will be run in the background, without a window +:code:`background` + The process will be run in the :italic:`background`, without a kitty window. -:italic:`clipboard` and :italic:`primary` - are meant to work with :option:`--stdin-source ` to copy - data to the system clipboard or primary selection. +:code:`clipboard`, :code:`primary` + These two are meant to work with :option:`--stdin-source ` to copy + data to the :italic:`system clipboard` or :italic:`primary selection`. #placeholder_for_formatting#