rnhmjoj/qutebrowser
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improve command documentation.

Browse Source
This commit is contained in:
Florian Bruhin 2014-08-03 00:33:39 +02:00
parent 6c4b21117c
commit 9e73cba333
6 changed files with 127 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
qutebrowser/browser/commands.py
View File

@ -302,27 +302,43 @@ class CommandDispatcher:
@cmdutils.register(instance='mainwindow.tabs.cmd')
def prev_page(self):
"""Open a "previous" link."""
"""Open a "previous" link.
This tries to automaticall click on typical "Previous Page" links using
some heuristics.
"""
self._prevnext(prev=True, newtab=False)
@cmdutils.register(instance='mainwindow.tabs.cmd')
def next_page(self):
"""Open a "next" link."""
"""Open a "next" link.
This tries to automatically click on typical "Next Page" links using
some heuristics.
"""
self._prevnext(prev=False, newtab=False)
@cmdutils.register(instance='mainwindow.tabs.cmd')
def prev_page_tab(self):
"""Open a "previous" link in a new tab."""
"""Open a "previous" link in a new tab.
This tries to automatically click on typical "Previous Page" links using
some heuristics.
"""
self._prevnext(prev=True, newtab=True)
@cmdutils.register(instance='mainwindow.tabs.cmd')
def next_page_tab(self):
"""Open a "next" link in a new tab."""
"""Open a "next" link in a new tab.
This tries to automatically click on typical "Previous Page" links using
some heuristics.
"""
self._prevnext(prev=False, newtab=True)
@cmdutils.register(instance='mainwindow.tabs.cmd', hide=True)
def scroll(self, dx, dy, count=1):
"""Scroll the current tab by count * dx/dy.
"""Scroll the current tab by 'count * dx/dy'.
Args:
dx: How much to scroll in x-direction.
@ -337,7 +353,10 @@ class CommandDispatcher:
@cmdutils.register(instance='mainwindow.tabs.cmd', hide=True)
def scroll_perc_x(self, perc=None, count=None):
"""Scroll the current tab to a specific percent of the page (horiz).
"""Scroll horizontally to a specific percentage of the page.
The percentage can be given either as argument or as count.
If no percentage is given, the page is scrolled to the end.
Args:
perc: Percentage to scroll.
@ -347,7 +366,10 @@ class CommandDispatcher:
@cmdutils.register(instance='mainwindow.tabs.cmd', hide=True)
def scroll_perc_y(self, perc=None, count=None):
"""Scroll the current tab to a specific percent of the page (vert).
"""Scroll vertically to a specific percentage of the page.
The percentage can be given either as argument or as count.
If no percentage is given, the page is scrolled to the end.
Args:
perc: Percentage to scroll.
@ -356,18 +378,18 @@ class CommandDispatcher:
self._scroll_percent(perc, count, Qt.Vertical)
@cmdutils.register(instance='mainwindow.tabs.cmd', hide=True)
def scroll_page(self, mx, my, count=1):
def scroll_page(self, x, y, count=1):
"""Scroll the frame page-wise.
Args:
mx: How many pages to scroll to the right.
my: How many pages to scroll down.
x: How many pages to scroll to the right.
y: How many pages to scroll down.
count: multiplier
"""
frame = self._tabs.currentWidget().page().currentFrame()
size = frame.geometry()
dx = int(count) * float(mx) * size.width()
dy = int(count) * float(my) * size.height()
dx = int(count) * float(x) * size.width()
dy = int(count) * float(y) * size.height()
cmdutils.check_overflow(dx, 'int')
cmdutils.check_overflow(dy, 'int')
frame.scroll(dx, dy)
@ -417,7 +439,7 @@ class CommandDispatcher:
"""Increase the zoom level for the current tab.
Args:
count: How many steps to take.
count: How many steps to zoom in.
"""
tab = self._tabs.currentWidget()
tab.zoom(count)
@ -427,17 +449,21 @@ class CommandDispatcher:
"""Decrease the zoom level for the current tab.
Args:
count: How many steps to take.
count: How many steps to zoom out.
"""
tab = self._tabs.currentWidget()
tab.zoom(-count)
@cmdutils.register(instance='mainwindow.tabs.cmd')
def zoom(self, zoom=None, count=None):
"""Set the zoom level for the current tab to [count] or 100 percent.
"""Set the zoom level for the current tab.
The zoom can be given as argument or as [count]. If neither of both is
given, the zoom is set to 100%.
Args:
count: How many steps to take.
zoom: The zoom percentage to set.
count: The zoom percentage to set.
"""
try:
level = cmdutils.arg_or_count(zoom, count, default=100)
@ -474,7 +500,7 @@ class CommandDispatcher:
@cmdutils.register(instance='mainwindow.tabs.cmd')
def undo(self):
"""Re-open a closed tab (optionally skipping [count] tabs)."""
"""Re-open a closed tab (optionally skipping [count] closed tabs)."""
if self._tabs.url_stack:
self._tabs.tabopen(self._tabs.url_stack.pop())
else:
@ -482,7 +508,7 @@ class CommandDispatcher:
@cmdutils.register(instance='mainwindow.tabs.cmd')
def tab_prev(self, count=1):
"""Switch to the previous tab, or skip [count] tabs.
"""Switch to the previous tab, or switch [count] tabs back.
Args:
count: How many tabs to switch back.
@ -497,7 +523,7 @@ class CommandDispatcher:
@cmdutils.register(instance='mainwindow.tabs.cmd')
def tab_next(self, count=1):
"""Switch to the next tab, or skip [count] tabs.
"""Switch to the next tab, or switch [count] tabs forward.
Args:
count: How many tabs to switch forward.
@ -548,6 +574,7 @@ class CommandDispatcher:
Args:
index: The tab index to focus, starting with 1.
count: The tab index to focus, starting with 1.
"""
try:
idx = cmdutils.arg_or_count(index, count, default=1,
@ -565,8 +592,8 @@ class CommandDispatcher:
"""Move the current tab.
Args:
direction: + or - for relative moving, None for absolute.
count: If moving absolutely: New position (or first).
direction: + or - for relative moving, none for absolute.
count: If moving absolutely: New position (default: 0)
If moving relatively: Offset.
"""
if direction is None:
@ -614,7 +641,7 @@ class CommandDispatcher:
don't care about the process anymore as soon as it's spawned.
Args:
*args: The commandline to execute
*args: The commandline to execute.
"""
log.procs.debug("Executing: {}".format(args))
subprocess.Popen(args)
@ -631,7 +658,6 @@ class CommandDispatcher:
Args:
cmd: The userscript to run.
args: Arguments to pass to the userscript.
url: A custom QUrl to use instead of the current url.
"""
url = self._tabs.current_url()
userscripts.run(cmd, *args, url=url)
@ -692,7 +718,10 @@ class CommandDispatcher:
@cmdutils.register(instance='mainwindow.tabs.cmd', modes=[KeyMode.insert],
hide=True)
def open_editor(self):
"""Open an external editor with the current form field.
"""Open an external editor with the currently selected form field.
The editor which should be launched can be configured via the
`general -> editor` config option.
//

14
qutebrowser/config/config.py
View File

@ -291,6 +291,10 @@ class ConfigManager(QObject):
//
Wrapper for the get-command to output the value in the status bar.
Args:
sectname: The section where the option is in.
optname: The name of the option.
"""
try:
val = self.get(sectname, optname, transformed=False)
@ -338,6 +342,11 @@ class ConfigManager(QObject):
//
Wrapper for self.set() to output exceptions in the status bar.
Args:
sectname: The section where the option is in.
optname: The name of the option.
value: The value to set.
"""
try:
self.set('conf', sectname, optname, value)
@ -354,6 +363,11 @@ class ConfigManager(QObject):
//
Wrapper for self.set() to output exceptions in the status bar.
Args:
sectname: The section where the option is in.
optname: The name of the option.
value: The value to set.
"""
try:
self.set('temp', sectname, optname, value)

6
qutebrowser/keyinput/modeman.py
View File

@ -213,10 +213,10 @@ class ModeManager(QObject):
@cmdutils.register(instance='modeman', hide=True)
def enter_mode(self, mode):
"""Enter mode as a command.
"""Enter a key mode.
Args:
mode: The mode to enter as a string.
mode: The mode to enter.
"""
try:
m = KeyMode[mode]
@ -225,7 +225,7 @@ class ModeManager(QObject):
self.enter(m, 'command')
def leave(self, mode, reason=None):
"""Leave a mode.
"""Leave a key mode.
Args:
mode: The name of the mode to leave.

4
qutebrowser/utils/debug.py
View File

@ -55,7 +55,7 @@ def debug_crash(typ='exception'):
"""Crash for debugging purposes.
Args:
typ: either 'exception' or 'segfault'
typ: either 'exception' or 'segfault'.
Raises:
raises Exception when typ is not segfault.
@ -80,7 +80,7 @@ def debug_all_widgets():
@cmdutils.register(debug=True)
def debug_all_objects():
"""Dump all children of an object recursively."""
"""Print a list of all objects to the debug log."""
s = QCoreApplication.instance().get_all_objects()
logger.debug(s)

65
qutebrowser/utils/readline.py
View File

@ -48,7 +48,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_backward_char(self):
"""Readline: Move back a character."""
"""Move back a character.
This acts like readline's backward-char.
"""
if self.widget is None:
return
self.widget.cursorBackward(False)
@ -56,7 +59,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_forward_char(self):
"""Readline: Move forward a character."""
"""Move forward a character.
This acts like readline's forward-char.
"""
if self.widget is None:
return
self.widget.cursorForward(False)
@ -64,7 +70,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_backward_word(self):
"""Readline: Move back to the start of the current or previous word."""
"""Move back to the start of the current or previous word.
This acts like readline's backward-word.
"""
if self.widget is None:
return
self.widget.cursorWordBackward(False)
@ -72,7 +81,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_forward_word(self):
"""Readline: Move forward to the end of the next word."""
"""Move forward to the end of the next word.
This acts like readline's forward-word.
"""
if self.widget is None:
return
self.widget.cursorWordForward(False)
@ -80,7 +92,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_beginning_of_line(self):
"""Readline: Move to the start of the current line."""
"""Move to the start of the line.
This acts like readline's beginning-of-line.
"""
if self.widget is None:
return
self.widget.home(False)
@ -88,7 +103,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_end_of_line(self):
"""Readline: Move to the end of the line."""
"""Move to the end of the line.
This acts like readline's end-of-line.
"""
if self.widget is None:
return
self.widget.end(False)
@ -96,7 +114,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_unix_line_discard(self):
"""Readline: Kill backward from cursor to the beginning of the line."""
"""Remove chars backward from the cursor to the beginning of the line.
This acts like readline's unix-line-discard.
"""
if self.widget is None:
return
self.widget.home(True)
@ -106,7 +127,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_kill_line(self):
"""Readline: Kill the text from point to the end of the line."""
"""Remove chars from the cursor to the end of the line.
This acts like readline's kill-line.
"""
if self.widget is None:
return
self.widget.end(True)
@ -116,7 +140,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_unix_word_rubout(self):
"""Readline: Kill the word behind point."""
"""Remove chars from the cursor to the beginning of the word.
This acts like readline's unix-word-rubout.
"""
if self.widget is None:
return
self.widget.cursorWordBackward(True)
@ -126,7 +153,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_kill_word(self):
"""Readline: Kill from point to the end of the current word."""
"""Remove chars from the cursor to the end of the current word.
This acts like readline's kill-word.
"""
if self.widget is None:
return
self.widget.cursorWordForward(True)
@ -136,7 +166,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_yank(self):
"""Readline: Yank the top of the kill ring into the buffer at point."""
"""Paste the most recently deleted text.
This acts like readline's yank.
"""
if self.widget is None or self.widget not in self.deleted:
return
self.widget.insert(self.deleted[self.widget])
@ -144,7 +177,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_delete_char(self):
"""Readline: Delete the character at point."""
"""Delete the character after the cursor.
This acts like readline's delete-char.
"""
if self.widget is None:
return
self.widget.del_()
@ -152,7 +188,10 @@ class ReadlineBridge:
@cmd.register(instance='rl_bridge', hide=True,
modes=[KeyMode.command, KeyMode.prompt])
def rl_backward_delete_char(self):
"""Readline: Delete the character behind the cursor."""
"""Delete the character before the cursor.
This acts like readline's backward-delete-char.
"""
if self.widget is None:
return
self.widget.backspace()

6
qutebrowser/widgets/statusbar/command.py
View File

@ -221,7 +221,7 @@ class Command(MinimalLineEdit):
@cmdutils.register(instance='mainwindow.status.cmd', hide=True,
modes=[KeyMode.command])
def command_history_prev(self):
"""Handle Up presses (go back in history)."""
"""Go back in the commandline history."""
try:
if not self.history.browsing:
item = self.history.start(self.text().strip())
@ -235,7 +235,7 @@ class Command(MinimalLineEdit):
@cmdutils.register(instance='mainwindow.status.cmd', hide=True,
modes=[KeyMode.command])
def command_history_next(self):
"""Handle Down presses (go forward in history)."""
"""Go forward in the commandline history."""
if not self.history.browsing:
return
try:
@ -248,7 +248,7 @@ class Command(MinimalLineEdit):
@cmdutils.register(instance='mainwindow.status.cmd', hide=True,
modes=[KeyMode.command])
def command_accept(self):
"""Handle the command in the status bar.
"""Execute the command currently in the commandline.
Emit:
got_cmd: If a new cmd was entered.