KittyPatch/kitty
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Use rst roles to format cli help text

Browse Source
This commit is contained in:
Kovid Goyal 2018-05-30 19:07:12 +05:30
parent fba37e73e7
commit 28803d9a5a
No known key found for this signature in database
GPG Key ID: 06BC317B515ACE7C
9 changed files with 94 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/_static/custom.css vendored
View File

@ -92,6 +92,10 @@ div.sphinxsidebar {
color: blue;
}
.env {
font-style: italic;
}
.italic {
font-style: italic;
}

1
docs/conf.py
View File

@ -91,6 +91,7 @@ rst_prolog = '''
.. role:: bold
.. role:: cyan
.. role:: title
.. role:: env
''' + create_shortcut_defs()

6
docs/conf.rst
View File

@ -18,6 +18,6 @@ You can also display the current configuration by running ``kitty
|kitty| looks for a config file in the OS config directories (usually
:file:`~/.config/kitty/kitty.conf` and additionally
:file:`~/Library/Preferences/kitty/kitty.conf` on macOS) but you can pass a
specific path via the ``--config`` option or use the ``KITTY_CONFIG_DIRECTORY``
environment variable. See the help for the :option:`--config` option in ``kitty
--help`` for full details.
specific path via the :option:`kitty --config` option or use the ``KITTY_CONFIG_DIRECTORY``
environment variable. See the :option:`kitty --config` option
for full details.

2
docs/remote-control.rst
View File

@ -102,7 +102,7 @@ instance of |kitty| using the :option:`--to` command line argument to ``kitty @`
Note that is all you want to do is run a single |kitty| "daemon" and have subsequent
|kitty| invocations appear as new top-level windows, you can use the simpler :option:`--single-instance`
|kitty| invocations appear as new top-level windows, you can use the simpler :option:`kitty --single-instance`
option, see ``kitty --help`` for that.
The builtin kitty shell

2
kittens/diff/main.py
View File

@ -372,7 +372,7 @@ type=list
--override -o
type=list
Override individual configuration options, can be specified multiple times.
Syntax: |_ name=value|. For example: |_ -o background=gray|
Syntax: :italic:`name=value`. For example: :italic:`-o background=gray`
'''.format, config_help=CONFIG_HELP.format(conf_name='diff', appname=appname))

14
kittens/icat/main.py
View File

@ -34,14 +34,14 @@ Horizontal alignment for the displayed image.
--place
Choose where on the screen to display the image. The image will
be scaled to fit into the specified rectangle. The syntax for
specifying rectanges is <|_ width|>x<|_ height|>@<|_ left|>x<|_ top|>. All measurements
are in cells (i.e. cursor positions) with the origin |_ (0, 0)| at
specifying rectanges is <:italic:`width`>x<:italic:`height`>@<:italic:`left`>x<:italic:`top`>. All measurements
are in cells (i.e. cursor positions) with the origin :italic:`(0, 0)` at
the top-left corner of the screen.
--scale-up
type=bool-set
When used in combination with |_ --place| it will cause images that
When used in combination with :option:`--place` it will cause images that
are smaller than the specified area to be scaled up to use as much
of the specified area as possible.
@ -56,8 +56,8 @@ type=choices
choices=detect,file,stream
default=detect
Which mechanism to use to transfer images to the terminal. The default is to
auto-detect. |_ file| means to use a temporary file and |_ stream| means to
send the data via terminal escape codes. Note that if you use the |_ file|
auto-detect. :italic:`file` means to use a temporary file and :italic:`stream` means to
send the data via terminal escape codes. Note that if you use the :italic:`file`
transfer mode and you are connecting over a remote session then image display
will not work.
@ -66,7 +66,7 @@ will not work.
type=bool-set
Detect support for image display in the terminal. If not supported, will exit
with exit code 1, otherwise will exit with code 0 and print the supported
transfer mode to stderr, which can be used with the |_ --transfer-mode| option.
transfer mode to stderr, which can be used with the :option:`--transfer-mode` option.
--detection-timeout
@ -78,7 +78,7 @@ detecting image display support.
--print-window-size
type=bool-set
Print out the window size as |_ widthxheight| (in pixels) and quit. This is a
Print out the window size as :italic:`widthxheight` (in pixels) and quit. This is a
convenience method to query the window size if using kitty icat from a
scripting language that cannot make termios calls.
'''

116
kitty/cli.py
View File

@ -19,29 +19,29 @@ sequence, which are merged. Use the special value NONE to not load a config
file.
If this option is not specified, config files are searched for in the order:
"$XDG_CONFIG_HOME/{appname}/{conf_name}.conf", "~/.config/{appname}/{conf_name}.conf", {macos_confpath}
"$XDG_CONFIG_DIRS/{appname}/{conf_name}.conf". The first one that exists is used as the
:file:`$XDG_CONFIG_HOME/{appname}/{conf_name}.conf`, :file:`~/.config/{appname}/{conf_name}.conf`, {macos_confpath}
:file:`$XDG_CONFIG_DIRS/{appname}/{conf_name}.conf`. The first one that exists is used as the
config file.
If the environment variable "KITTY_CONFIG_DIRECTORY" is specified, that
If the environment variable :env:`KITTY_CONFIG_DIRECTORY` is specified, that
directory is always used and the above searching does not happen.
If "/etc/xdg/{appname}/{conf_name}.conf" exists it is merged before (i.e. with lower
If :file:`/etc/xdg/{appname}/{conf_name}.conf` exists it is merged before (i.e. with lower
priority) than any user config files. It can be used to specify system-wide
defaults for all users.
'''.replace('{macos_confpath}', '~/Library/Preferences/{appname}/{conf_name}.conf, ' if is_macos else '')
'''.replace('{macos_confpath}', ':file:`~/Library/Preferences/{appname}/{conf_name}.conf`,' if is_macos else '')
OPTIONS = '''
--class
dest=cls
default={appname}
condition=not is_macos
Set the class part of the |_ WM_CLASS| window property
Set the class part of the :italic:`WM_CLASS` window property
--name
condition=not is_macos
Set the name part of the |_ WM_CLASS| property (defaults to using the value from |_ --class|)
Set the name part of the :italic:`WM_CLASS` property (defaults to using the value from :option:`{appname} --class`)
--title
@ -56,7 +56,7 @@ type=list
--override -o
type=list
Override individual configuration options, can be specified multiple times.
Syntax: |_ name=value|. For example: |_ -o font_size=20|
Syntax: :italic:`name=value`. For example: :option:`kitty -o` font_size=20
--directory -d
@ -71,33 +71,33 @@ Detach from the controlling terminal, if any
--session
Path to a file containing the startup |_ session| (tabs, windows, layout, programs).
Path to a file containing the startup :italic:`session` (tabs, windows, layout, programs).
See the README file for details and an example.
--single-instance -1
type=bool-set
If specified only a single instance of |_ {appname}| will run. New invocations will
instead create a new top-level window in the existing |_ {appname}| instance. This
allows |_ {appname}| to share a single sprite cache on the GPU and also reduces
startup time. You can also have separate groups of |_ {appname}| instances by using the
|_ --instance-group| option
If specified only a single instance of :italic:`{appname}` will run. New invocations will
instead create a new top-level window in the existing :italic:`{appname}` instance. This
allows :italic:`{appname}` to share a single sprite cache on the GPU and also reduces
startup time. You can also have separate groups of :italic:`{appname}` instances by using the
:option:`kitty --instance-group` option
--instance-group
Used in combination with the |_ --single-instance| option. All |_ {appname}| invocations
with the same |_ --instance-group| will result in new windows being created
in the first |_ {appname}| instance within that group
Used in combination with the :option:`kitty --single-instance` option. All :italic:`{appname}` invocations
with the same :option:`kitty --instance-group` will result in new windows being created
in the first :italic:`{appname}` instance within that group
--listen-on
Tell kitty to listen on the specified address for control
messages. For example, |_ --listen-on=unix:/tmp/mykitty| or
|_ --listen-on=tcp:localhost:12345|. On Linux systems, you can also use abstract
UNIX sockets, not associated with a file, like this: |_ --listen-on=unix:@mykitty|.
To control kitty, you can send it commands with |_ kitty @| using the |_ --to| option
messages. For example, :option:`{appname} --listen-on` unix:/tmp/mykitty or
:option:`{appname} --listen-on` tcp:localhost:12345. On Linux systems, you can also use abstract
UNIX sockets, not associated with a file, like this: :option:`{appname} --listen-on` unix:@mykitty.
To control kitty, you can send it commands with :italic:`kitty @` using the :option:`kitty @ --to` option
to specify this address. Note that this option will be ignored, unless you set
|_ allow_remote_control| to yes in |_ kitty.conf|
:italic:`allow_remote_control` to yes in |kitty.conf|.
# Debugging options
@ -114,7 +114,7 @@ Output commands received from child process to stdout
--replay-commands
Replay previously dumped commands. Specify the path to a dump file previously created by --dump-commands. You
can open a new kitty window to replay the commands with:
can open a new kitty window to replay the commands with::
kitty sh -c "kitty --replay-commands /path/to/dump/file; read"
@ -125,7 +125,8 @@ Path to file in which to store the raw bytes received from the child process
--debug-gl
type=bool-set
Debug OpenGL commands. This will cause all OpenGL calls to check for errors instead of ignoring them. Useful when debugging rendering problems
Debug OpenGL commands. This will cause all OpenGL calls to check for errors
instead of ignoring them. Useful when debugging rendering problems
--debug-font-fallback
@ -182,6 +183,19 @@ def title(x):
return blue(bold(x))
def option(x):
parts = map(bold, x.split())
return ' '.join(parts)
def env(x):
return italic(x)
def file(x):
return italic(x)
def parse_option_spec(spec=OPTIONS):
NORMAL, METADATA, HELP = 'NORMAL', 'METADATA', 'HELP'
state = NORMAL
@ -193,7 +207,7 @@ def parse_option_spec(spec=OPTIONS):
current_cmd = None
for line in lines:
line = line.strip()
line = line.rstrip()
if state is NORMAL:
if not line:
continue
@ -220,10 +234,11 @@ def parse_option_spec(spec=OPTIONS):
current_cmd['choices'] = {x.strip() for x in current_cmd['choices'].split(',')}
elif state is HELP:
if line:
current_cmd['help'] += ' ' + line.lstrip()
spc = '' if current_cmd['help'].endswith('\n') else ' '
current_cmd['help'] += spc + line
else:
if prev_line:
current_cmd['help'] += '\n\n\t'
current_cmd['help'] += '\n\n'
else:
state = NORMAL
(seq if current_cmd.get('condition', True) else disabled).append(current_cmd)
@ -236,33 +251,17 @@ def parse_option_spec(spec=OPTIONS):
def prettify(text):
role_map = globals()
def sub(m):
t = m.group(2)
for ch in m.group(1):
t = {'C': cyan, '_': italic, '*': bold, 'G': green, 'T': title}[ch](t)
return t
role, text = m.group(1, 2)
return role_map[role](text)
text = re.sub(r'[|]([a-zA-Z_*]+?) (.+?)[|]', sub, text)
return text
text = re.sub(r':([a-z]+):`([^`]+)`', sub, text)
return text.replace('|kitty.conf|', italic('kitty.conf'))
def prettify_rst(text):
def roled(role):
def f(x):
if x.startswith(':'):
return x
return ':{}:`{}`'.format(role, x.replace('`', r'\`'))
return f
def sub(m):
t = m.group(2)
for ch in m.group(1):
t = {'C': roled('cyan'), '_': roled('italic'), '*': roled('bold'), 'G': roled('green'), 'T': roled('title')}[ch](t)
return t
text = re.sub(r'[|]([a-zA-Z_*]+?) (.+?)[|]', sub, text)
return text
@ -307,6 +306,12 @@ def wrap(text, limit=80):
return reversed(lines)
default_msg = (
'Run the :italic:`{appname}` terminal emulator. You can also specify the :italic:`program` to run inside :italic:`{appname}` as normal'
' arguments following the :italic:`options`. For example: {appname} /bin/sh'
).format(appname=appname)
def print_help_for_seq(seq, usage, message, appname):
from kitty.utils import screen_size_function
screen_size = screen_size_function()
@ -333,10 +338,7 @@ def print_help_for_seq(seq, usage, message, appname):
optstring = '[options] ' if seq else ''
a('{}: {} {}{}'.format(title('Usage'), bold(yellow(appname)), optstring, usage))
a('')
message = message or (
'Run the |G {appname}| terminal emulator. You can also specify the |_ program| to run inside |_ {appname}| as normal'
' arguments following the |_ options|. For example: {appname} /bin/sh'
).format(appname=appname)
message = message or default_msg
wa(prettify(message))
a('')
if seq:
@ -386,10 +388,7 @@ def seq_as_rst(seq, usage, message, appname):
a('')
a(' {} {}{}'.format(appname, optstring, usage))
a('')
message = message or (
'Run the |G {appname}| terminal emulator. You can also specify the |_ program| to run inside |_ {appname}| as normal'
' arguments following the |_ options|. For example: {appname} /bin/sh'
).format(appname=appname)
message = message or default_msg
a(prettify_rst(message))
a('')
if seq:
@ -413,11 +412,6 @@ def seq_as_rst(seq, usage, message, appname):
defval = opt.get('default')
t = help_text.replace('%default', str(defval)).strip()
a('')
t = re.sub(r':$', '::', t, flags=re.MULTILINE)
t = t.replace('::\n\n\t ', '::\n \n ')
t = t.replace('\n\n\t ', '\n \n')
t = re.sub(r'(--[a-zA-Z0-9-]+)', r':option:`{} \1` '.format(appname), t)
t = re.sub('"(.+?)"', r'``\1``', t)
a(textwrap.indent(prettify_rst(t), ' ' * 4))
if defval is not None:
a(textwrap.indent('Default: {}'.format(defval), ' ' * 4))

36
kitty/cmds.py
View File

@ -46,19 +46,19 @@ def cmd(short_desc, desc=None, options_spec=None, no_response=False, argspec='..
MATCH_WINDOW_OPTION = '''\
--match -m
The window to match. Match specifications are of the form:
|_ field:regexp|. Where field can be one of: id, title, pid, cwd, cmdline, num.
You can use the |_ ls| command to get a list of windows. Note that for
:italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline, num.
You can use the :italic:`ls` command to get a list of windows. Note that for
numeric fields such as id, pid and num the expression is interpreted as a number,
not a regular expression. The field num refers to the window position in the current tab,
starting from zero and counting clockwise (this is the same as the order in which the
windows are reported by the |_ ls| command). The window id of the current window
windows are reported by the :italic:`ls` command). The window id of the current window
is available as the KITTY_WINDOW_ID environment variable.
'''
MATCH_TAB_OPTION = '''\
--match -m
The tab to match. Match specifications are of the form:
|_ field:regexp|. Where field can be one of: id, title, pid, cwd, cmdline.
You can use the |_ ls| command to get a list of tabs. Note that for
:italic:`field:regexp`. Where field can be one of: id, title, pid, cwd, cmdline.
You can use the :italic:`ls` command to get a list of tabs. Note that for
numeric fields such as id and pid the expression is interpreted as a number,
not a regular expression. When using title or id, first a matching tab is
looked for and if not found a matching window is looked for, and the tab
@ -70,10 +70,10 @@ for that window is used.
@cmd(
'List all tabs/windows',
'List all windows. The list is returned as JSON tree. The top-level is a list of'
' operating system {appname} windows. Each OS window has an |_ id| and a list'
' of |_ tabs|. Each tab has its own |_ id|, a |_ title| and a list of |_ windows|.'
' Each window has an |_ id|, |_ title|, |_ current working directory|, |_ process id (PID)| and'
' |_ command-line| of the process running in the window.\n\n'
' operating system {appname} windows. Each OS window has an :italic:`id` and a list'
' of :italic:`tabs`. Each tab has its own :italic:`id`, a :italic:`title` and a list of :italic:`windows`.'
' Each window has an :italic:`id`, :italic:`title`, :italic:`current working directory`, :italic:`process id (PID)` and'
' :italic:`command-line` of the process running in the window.\n\n'
'You can use these criteria to select windows/tabs for the other commands.'.format(appname=appname),
argspec=''
)
@ -110,14 +110,14 @@ def set_font_size(boss, window, payload):
@cmd(
'Send arbitrary text to specified windows',
'Send arbitrary text to specified windows. The text follows Python'
' escaping rules. So you can use escapes like |_ \\x1b| to send control codes'
' and |_ \\u21fa| to send unicode characters. If you use the |_ --match| option'
' escaping rules. So you can use escapes like :italic:`\\x1b` to send control codes'
' and :italic:`\\u21fa` to send unicode characters. If you use the :option:`kitty @ send-text --match` option'
' the text will be sent to all matched windows. By default, text is sent to'
' only the currently active window.',
options_spec=MATCH_WINDOW_OPTION + '''\n
--stdin
type=bool-set
Read the text to be sent from |_ stdin|. Note that in this case the text is sent as is,
Read the text to be sent from :italic:`stdin`. Note that in this case the text is sent as is,
not interpreted for escapes. If stdin is a terminal, you can press Ctrl-D to end reading.
@ -202,7 +202,7 @@ def send_text(boss, window, payload):
# set_window_title {{{
@cmd(
'Set the window title',
'Set the title for the specified window(s). If you use the |_ --match| option'
'Set the title for the specified window(s). If you use the :option:`kitty @ set-window-title --match` option'
' the title will be set for all matched windows. By default, only the window'
' in which the command is run is affected. If you do not specify a title, the'
' last title set by the child process running in the window will be used.',
@ -229,7 +229,7 @@ def set_window_title(boss, window, payload):
# set_tab_title {{{
@cmd(
'Set the tab title',
'Set the title for the specified tab(s). If you use the |_ --match| option'
'Set the title for the specified tab(s). If you use the :option:`kitty @ set-tab-title --match` option'
' the title will be set for all matched tabs. By default, only the tab'
' in which the command is run is affected. If you do not specify a title, the'
' title of the currently active window in the tab is used.',
@ -297,8 +297,8 @@ The number of cells to change the size by, can be negative to decrease the size.
type=choices
choices=horizontal,vertical,reset
default=horizontal
The axis along which to resize. If |_ horizontal|, it will make the window wider or narrower by the specified increment.
If |_ vertical|, it will make the window taller or shorter by the specified increment. The special value |_ reset| will
The axis along which to resize. If :italic:`horizontal`, it will make the window wider or narrower by the specified increment.
If :italic:`vertical`, it will make the window taller or shorter by the specified increment. The special value :italic:`reset` will
reset the layout to its default configuration.
@ -363,12 +363,12 @@ def close_tab(boss, window, payload):
# new_window {{{
@cmd(
'Open new window',
'Open a new window in the specified tab. If you use the |_ --match| option'
'Open a new window in the specified tab. If you use the :option:`kitty @ new-window --match` option'
' the first matching tab is used. Otherwise the currently active tab is used.'
' Prints out the id of the newly opened window. Any command line arguments'
' are assumed to be the command line used to run in the new window, if none'
' are provided, the default shell is run. For example:\n'
'|_ kitty @ new-window --title Email mutt|',
':italic:`kitty @ new-window --title Email mutt`',
options_spec=MATCH_TAB_OPTION + '''\n
--title
The title for the new window. By default it will use the title set by the

8
kitty/remote_control.py
View File

@ -87,13 +87,13 @@ all_commands = tuple(sorted(cmap))
def parse_rc_args(args):
cmds = (' |G {}|\n {}'.format(cmap[c].name, cmap[c].short_desc) for c in all_commands)
cmds = (' :green:`{}`\n {}'.format(cmap[c].name, cmap[c].short_desc) for c in all_commands)
msg = (
'Control {appname} by sending it commands. Add'
' |_ allow_remote_control yes| to kitty.conf for this'
' to work.\n\n|T Commands|:\n{cmds}\n\n'
' :italic:`allow_remote_control yes` to |kitty.conf| for this'
' to work.\n\n:title:`Commands`:\n{cmds}\n\n'
'You can get help for each individual command by using:\n'
'{appname} @ |_ command| -h'
'{appname} @ :italic:`command` -h'
).format(appname=appname, cmds='\n'.join(cmds))
return parse_args(args[1:], global_options_spec, 'command ...', msg, '{} @'.format(appname))