diff --git a/docs/extract-rst-targets.py b/docs/extract-rst-targets.py index 41b39d897..b349eb385 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: @@ -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} 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/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/cli.py b/kitty/cli.py index 39e98ad1e..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 @@ -193,6 +195,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]] @@ -779,7 +796,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/conf/types.py b/kitty/conf/types.py index 31fb480c1..5b89005df 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': + return f'{t} <{website_url(q)}>' + 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) 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() 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# 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:: 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)