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

Initial doc update with new settings

Browse Source
This commit is contained in:
Florian Bruhin 2017-07-01 22:58:50 +02:00
parent 94ac2ca56c
commit 25ab3b30c2
6 changed files with 2157 additions and 2206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
doc/help/commands.asciidoc
View File

@ -281,7 +281,7 @@ Syntax: +:edit-url [*--bg*] [*--tab*] [*--window*] ['url']+
Navigate to a url formed in an external editor.
The editor which should be launched can be configured via the `general -> editor` config option.
The editor which should be launched can be configured via the `editor.command` config option.
==== positional arguments
* +'url'+: URL to edit; defaults to the current page url.
@ -338,7 +338,7 @@ Show help about a command or setting.
* +'topic'+: The topic to show help for.
- :__command__ for commands.
- __option.foo.bar__ for settings.
- __section__.__option__ for settings.
==== optional arguments
@ -408,7 +408,7 @@ Start hinting.
* +*-m*+, +*--mode*+: The hinting mode to use.
- `number`: Use numeric hints.
- `letter`: Use the chars in the hints.chars settings.
- `letter`: Use the chars in the hints.chars setting.
- `word`: Use hint words based on the html elements and the
extra words.
@ -545,7 +545,7 @@ For `increment` and `decrement`, the number to change the URL by. For `up`, the
[[open]]
=== open
Syntax: +:open [*--implicit*] [*--bg*] [*--tab*] [*--window*] [*--secure*] [*--private*]
Syntax: +:open [*--related*] [*--bg*] [*--tab*] [*--window*] [*--secure*] [*--private*]
['url']+
Open a URL in the current/[count]th tab.
@ -556,7 +556,7 @@ If the URL contains newlines, each line gets opened in its own tab.
* +'url'+: The URL to open.
==== optional arguments
* +*-i*+, +*--implicit*+: If opening a new tab, treat the tab as implicit (like clicking on a link).
* +*-r*+, +*--related*+: If opening a new tab, position the tab as related to the current one (like clicking on a link).
* +*-b*+, +*--bg*+: Open in a new background tab.
* +*-t*+, +*--tab*+: Open in a new tab.
@ -632,8 +632,17 @@ Save the current page as a quickmark.
[[quit]]
=== quit
Syntax: +:quit [*--save*] ['session']+
Quit qutebrowser.
==== positional arguments
* +'session'+: The name of the session to save.
==== optional arguments
* +*-s*+, +*--save*+: When given, save the open windows even if auto_save.session is turned off.
[[record-macro]]
=== record-macro
Syntax: +:record-macro ['register']+
@ -752,7 +761,7 @@ Syntax: +:session-save [*--current*] [*--quiet*] [*--force*] [*--only-active-win
Save a session.
==== positional arguments
* +'name'+: The name of the session. If not given, the session configured in general -> session-default-name is saved.
* +'name'+: The name of the session. If not given, the session configured in session_default_name is saved.
==== optional arguments
@ -764,19 +773,18 @@ Save a session.
[[set]]
=== set
Syntax: +:set [*--temp*] [*--print*] ['section'] ['option'] ['values' ['values' ...]]+
Syntax: +:set [*--temp*] [*--print*] ['option'] ['values' ['values' ...]]+
Set an option.
If the option name ends with '?', the value of the option is shown instead. If the option name ends with '!' and it is a boolean value, toggle it.
==== positional arguments
* +'section'+: The section where the option is in.
* +'option'+: The name of the option.
* +'values'+: The value to set, or the values to cycle through.
==== optional arguments
* +*-t*+, +*--temp*+: Set value temporarily.
* +*-t*+, +*--temp*+: Set value temporarily until qutebrowser is closed.
* +*-p*+, +*--print*+: Print the value after setting.
[[set-cmd-text]]
@ -843,7 +851,7 @@ Close the current/[count]th tab.
==== optional arguments
* +*-p*+, +*--prev*+: Force selecting the tab before the current tab.
* +*-n*+, +*--next*+: Force selecting the tab after the current tab.
* +*-o*+, +*--opposite*+: Force selecting the tab in the opposite direction of what's configured in 'tabs->select-on-remove'.
* +*-o*+, +*--opposite*+: Force selecting the tab in the opposite direction of what's configured in 'tabs.select_on_remove'.
* +*-f*+, +*--force*+: Avoid confirmation for pinned tabs.
@ -911,7 +919,7 @@ Close all tabs except for the current one.
=== tab-pin
Pin/Unpin the current/[count]th tab.
Pinning a tab shrinks it to tabs->pinned-width size. Attempting to close a pinned tab will cause a confirmation, unless --force is passed.
Pinning a tab shrinks it to `tabs.width.pinned` size. Attempting to close a pinned tab will cause a confirmation, unless --force is passed.
==== count
The tab index to pin or unpin
@ -931,8 +939,7 @@ Unbind a keychain.
==== positional arguments
* +'key'+: The keychain or special key (inside <...>) to unbind.
* +'mode'+: A comma-separated list of modes to unbind the key in (default: `normal`).
* +'mode'+: A mode to unbind the key in (default: `normal`).
[[undo]]
=== undo
@ -1043,6 +1050,7 @@ How many steps to zoom out.
|<<move-to-start-of-line,move-to-start-of-line>>|Move the cursor or selection to the start of the line.
|<<move-to-start-of-next-block,move-to-start-of-next-block>>|Move the cursor or selection to the start of next block.
|<<move-to-start-of-prev-block,move-to-start-of-prev-block>>|Move the cursor or selection to the start of previous block.
|<<nop,nop>>|Do nothing.
|<<open-editor,open-editor>>|Open an external editor with the currently selected form field.
|<<prompt-accept,prompt-accept>>|Accept the current prompt.
|<<prompt-item-focus,prompt-item-focus>>|Shift the focus of the prompt file completion menu to another item.
@ -1290,11 +1298,15 @@ Move the cursor or selection to the start of previous block.
==== count
How many blocks to move.
[[nop]]
=== nop
Do nothing.
[[open-editor]]
=== open-editor
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.
The editor which should be launched can be configured via the `editor.command` config option.
[[prompt-accept]]
=== prompt-accept

4179
doc/help/settings.asciidoc
View File

File diff suppressed because it is too large Load Diff

2
doc/qutebrowser.1.asciidoc
View File

@ -44,7 +44,7 @@ show it.
*-V*, *--version*::
Show version and quit.
*-s* 'SECTION' 'OPTION' 'VALUE', *--set* 'SECTION' 'OPTION' 'VALUE'::
*-s* 'OPTION' 'VALUE', *--set* 'OPTION' 'VALUE'::
Set a temporary setting for this session.
*-r* 'SESSION', *--restore* 'SESSION'::

22
qutebrowser/config/configdata.py
View File

@ -79,7 +79,8 @@ MONOSPACE = (' xos4 Terminus, Terminus, Monospace, '
Option = collections.namedtuple('Option', ['name', 'typ', 'default',
'backends', 'description'])
'backends', 'conditional_backends',
'description'])
def _raise_invalid_node(name, what, node):
@ -183,15 +184,20 @@ def _parse_yaml_backends(name, node):
QtWebKit: true
QtWebEngine: Qt 5.9
-> setting available based on the given conditionals.
Return:
A list of backends, and a boolean whether the list is conditional based
on the Qt version.
"""
if node is None:
return [usertypes.Backend.QtWebKit, usertypes.Backend.QtWebEngine]
return ([usertypes.Backend.QtWebKit, usertypes.Backend.QtWebEngine],
False)
elif node == 'QtWebKit':
return [usertypes.Backend.QtWebKit]
return ([usertypes.Backend.QtWebKit], False)
elif node == 'QtWebEngine':
return [usertypes.Backend.QtWebEngine]
return ([usertypes.Backend.QtWebEngine], False)
elif isinstance(node, dict):
return _parse_yaml_backends_dict(name, node)
return (_parse_yaml_backends_dict(name, node), True)
_raise_invalid_node(name, 'backends', node)
@ -214,11 +220,15 @@ def _read_yaml(yaml_data):
raise ValueError("Invalid keys {} for {}".format(
option.keys(), name))
backends, conditional_backends = _parse_yaml_backends(
name, option.get('backend', None))
parsed[name] = Option(
name=name,
typ=_parse_yaml_type(name, option['type']),
default=option['default'],
backends=_parse_yaml_backends(name, option.get('backend', None)),
backends=backends,
conditional_backends=conditional_backends,
description=option['desc'])
# Make sure no key shadows another.

13
qutebrowser/config/configdata.yml
View File

@ -392,8 +392,10 @@ content.netrc_file:
type:
name: File
none_ok: true
desc: Set location of a netrc-file for HTTP authentication. If unset, ~/.netrc
is used.
desc: >-
Location of a netrc-file for HTTP authentication.
If unset, `~/.netrc` is used.
content.notifications:
default: ask
@ -640,8 +642,11 @@ downloads.location.directory:
type:
name: Directory
none_ok: true
desc: The directory to save downloads to. If unset, a sensible os-specific
default is used. Will expand environment variables.
desc: >-
The directory to save downloads to.
If unset, a sensible os-specific default is used.
Will expand environment variables.
downloads.location.prompt:
default: true

107
scripts/dev/src2asciidoc.py
View File

@ -144,19 +144,14 @@ def _get_command_quickref(cmds):
def _get_setting_quickref():
"""Generate the settings quick reference."""
out = []
for sectname, sect in configdata.DATA.items():
if not getattr(sect, 'descriptions'):
continue
out.append("")
out.append(".Quick reference for section ``{}''".format(sectname))
out.append('[options="header",width="75%",cols="25%,75%"]')
out.append('|==============')
out.append('|Setting|Description')
for optname, _option in sect.items():
desc = sect.descriptions[optname].splitlines()[0]
out.append('|<<{}-{},{}>>|{}'.format(
sectname, optname, optname, desc))
out.append('|==============')
out.append('')
out.append('[options="header",width="75%",cols="25%,75%"]')
out.append('|==============')
out.append('|Setting|Description')
for opt in sorted(configdata.DATA.values()):
desc = opt.description.splitlines()[0]
out.append('|<<{},{}>>|{}'.format(opt.name, opt.name, desc))
out.append('|==============')
return '\n'.join(out)
@ -326,8 +321,6 @@ def generate_commands(filename):
hidden_cmds = []
debug_cmds = []
for name, cmd in cmdutils.cmd_dict.items():
if name in cmdutils.aliases:
continue
if cmd.deprecated:
continue
if cmd.hide:
@ -363,63 +356,59 @@ def generate_commands(filename):
f.write(_get_command_doc(name, cmd))
def _generate_setting_section(f, sectname, sect):
def _generate_setting_option(f, opt):
"""Generate documentation for a single section."""
version_dependent_options = [('network', 'proxy'),
('general', 'print-element-backgrounds')]
for optname, option in sect.items():
f.write("\n")
f.write('[[{}]]'.format(opt.name) + "\n")
f.write("== {}".format(opt.name) + "\n")
f.write(opt.description + "\n")
f.write("\n")
valid_values = opt.typ.get_valid_values()
if valid_values is not None:
f.write("Valid values:\n")
f.write("\n")
f.write('[[{}-{}]]'.format(sectname, optname) + "\n")
f.write("=== {}".format(optname) + "\n")
f.write(sect.descriptions[optname] + "\n")
for val in valid_values:
try:
desc = valid_values.descriptions[val]
f.write(" * +{}+: {}".format(val, desc) + "\n")
except KeyError:
f.write(" * +{}+".format(val) + "\n")
f.write("\n")
valid_values = option.typ.get_valid_values()
if valid_values is not None:
f.write("Valid values:\n")
f.write("\n")
for val in valid_values:
try:
desc = valid_values.descriptions[val]
f.write(" * +{}+: {}".format(val, desc) + "\n")
except KeyError:
f.write(" * +{}+".format(val) + "\n")
f.write("\n")
if opt.name == 'bindings.default':
# FIXME:conf
pass
elif opt.default:
f.write("Default: +pass:[{}]+\n".format(html.escape(
opt.typ.to_str(opt.default))))
else:
f.write("Default: empty\n")
if option.default():
f.write("Default: +pass:[{}]+\n".format(html.escape(
option.default())))
else:
f.write("Default: empty\n")
if (option.backends is None or
(sectname, optname) in version_dependent_options):
pass
elif option.backends == [usertypes.Backend.QtWebKit]:
f.write("\nThis setting is only available with the QtWebKit "
"backend.\n")
elif option.backends == [usertypes.Backend.QtWebEngine]:
f.write("\nThis setting is only available with the QtWebEngine "
"backend.\n")
else:
raise ValueError("Invalid value {!r} for option.backends".format(
option.backends))
all_backends = [usertypes.Backend.QtWebKit, usertypes.Backend.QtWebEngine]
if opt.backends == all_backends or opt.conditional_backends:
pass
elif opt.backends == [usertypes.Backend.QtWebKit]:
f.write("\nThis setting is only available with the QtWebKit "
"backend.\n")
elif opt.backends == [usertypes.Backend.QtWebEngine]:
f.write("\nThis setting is only available with the QtWebEngine "
"backend.\n")
else:
raise ValueError("Invalid value {!r} for opt.backends"
.format(opt.backends))
def generate_settings(filename):
"""Generate the complete settings section."""
configdata.init()
with _open_file(filename) as f:
f.write(FILE_HEADER)
f.write("= Settings\n")
f.write(_get_setting_quickref() + "\n")
for sectname, sect in configdata.DATA.items():
f.write("\n")
f.write("== {}".format(sectname) + "\n")
f.write(configdata.SECTION_DESC[sectname] + "\n")
if not getattr(sect, 'descriptions'):
pass
else:
_generate_setting_section(f, sectname, sect)
for opt in sorted(configdata.DATA.values()):
_generate_setting_option(f, opt)
def _get_authors():