Merge branch 'docs' of https://github.com/page-down/kitty

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}
 

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:
 

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.
         ''')

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"
 
 

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)

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()

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 <window>` in the current tab
 
-:term:`tab`
-    a new tab in the current :term:`OS Window <os_window>`
+:code:`tab`
+    A new :term:`tab` in the current OS window
 
-:term:`os-window <os_window>`
-    a new operating system window
+:code:`os-window <os_window>`
+    A new :term:`operating system window <os_window>`
 
-:term:`overlay`
-    an overlay window covering the current active window.
+:code:`overlay`
+    An :term:`overlay window <overlay>` 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 <launch --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 <launch --stdin-source>` to copy
+    data to the :italic:`system clipboard` or :italic:`primary selection`.
 
 #placeholder_for_formatting#
 

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::

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)