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

Improve settings value documentation.

Browse Source
This commit is contained in:
Florian Bruhin 2014-08-02 22:54:15 +02:00
parent f8c995d58d
commit aa8d66f092
2 changed files with 92 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

183
qutebrowser/config/configdata.py
View File

@ -64,7 +64,7 @@ FIRST_COMMENT = r"""
SECTION_DESC = { SECTION_DESC = {
'general': "General/misc. options.", 'general': "General/miscellaneous options.",
'ui': "General options related to the user interface.", 'ui': "General options related to the user interface.",
'input': "Options related to input modes.", 'input': "Options related to input modes.",
'network': "Settings related to the network.", 'network': "Settings related to the network.",
@ -113,7 +113,8 @@ SECTION_DESC = {
"Keybindings for passthrough mode.\n" "Keybindings for passthrough mode.\n"
"Since normal keypresses are passed through, only special keys are " "Since normal keypresses are passed through, only special keys are "
"supported in this mode.\n" "supported in this mode.\n"
"An useful command to map here is the hidden command leave-mode."), "Useful hidden commands to map in this section:\n\n"
" * `leave-mode`: Leave the passthrough mode."),
'keybind.command': ( 'keybind.command': (
"Keybindings for command mode.\n" "Keybindings for command mode.\n"
"Since normal keypresses are passed through, only special keys are " "Since normal keypresses are passed through, only special keys are "
@ -161,7 +162,7 @@ SECTION_DESC = {
'fonts': ( 'fonts': (
"Fonts used for the UI, with optional style/weight/size.\n\n" "Fonts used for the UI, with optional style/weight/size.\n\n"
" * Style: `normal`/`italic`/`oblique`\n" " * Style: `normal`/`italic`/`oblique`\n"
" * Weight: `normal`, `bold`, 100..900\n" " * Weight: `normal`, `bold`, `100`..`900`\n"
" * Size: _number_ `px`/`pt`\n\n" " * Size: _number_ `px`/`pt`\n\n"
"Note: The font for hints is a true CSS font, not a Qt-CSS one, " "Note: The font for hints is a true CSS font, not a Qt-CSS one, "
"because of that, a general ``Monospace'' family is enough and we " "because of that, a general ``Monospace'' family is enough and we "
@ -173,11 +174,11 @@ DATA = OrderedDict([
('general', sect.KeyValue( ('general', sect.KeyValue(
('ignore-case', ('ignore-case',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Whether to do case-insensitive searching."), "Whether to find text on a page case-insensitively."),
('wrap-search', ('wrap-search',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Whether to wrap search to the top when arriving at the end."), "Whether to wrap finding text to the top when arriving at the end."),
('startpage', ('startpage',
SettingValue(types.List(), 'http://www.duckduckgo.com'), SettingValue(types.List(), 'http://www.duckduckgo.com'),
@ -198,37 +199,44 @@ DATA = OrderedDict([
('editor', ('editor',
SettingValue(types.ShellCommand(placeholder=True), 'gvim -f "{}"'), SettingValue(types.ShellCommand(placeholder=True), 'gvim -f "{}"'),
"The editor (and arguments) to use for the open-editor binding. " "The editor (and arguments) to use for the `open-editor` command.\n\n"
"Use `{}` for the filename. Gets split via shutils."), "Use `{}` for the filename. The value gets split like in a shell, so "
"you can use `\"` or `'` to quote arguments."),
('private-browsing', ('private-browsing',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"Private browsing prevents WebKit from recording visited pages in " "Do not record visited pages in the history or store web page "
"the history and storing web page icons."), "icons."),
('developer-extras', ('developer-extras',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"Enables extra tools for Web developers (e.g. webinspector)."), "Enable extra tools for Web developers.\n\n"
"This needs to be enabled for `:inspector` to work and also adds an "
"_Inspect_ entry to the context menu."),
('print-element-backgrounds', ('print-element-backgrounds',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Specifies whether the background color and images are also drawn " "Whether the background color and images are also drawn when the "
"when the page is printed."), "page is printed."),
('xss-auditing', ('xss-auditing',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"Specifies whether load requests should be monitored for cross-site " "Whether load requests should be monitored for cross-site scripting "
"scripting attempts. Suspicious scripts will be blocked and reported " "attempts.\n\n"
"in the inspector's JavaScript console. Enabling this feature might " "Suspicious scripts will be blocked and reported in the inspector's "
"have an impact on performance."), "JavaScript console. Enabling this feature might have an impact on "
"performance."),
('site-specific-quirks', ('site-specific-quirks',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"This setting enables WebKit's workaround for broken sites."), "Enable workarounds for broken sites."),
('default-encoding', ('default-encoding',
SettingValue(types.String(none_ok=True), ''), SettingValue(types.String(none_ok=True), ''),
"Default encoding to use for websites."), "Default encoding to use for websites.\n\n"
"The encoding must be a string describing an encoding such as "
'_utf-8_, _iso-8859-1_, etc. If left empty a default value will be '
"used."),
)), )),
('ui', sect.KeyValue( ('ui', sect.KeyValue(
@ -256,63 +264,31 @@ DATA = OrderedDict([
('zoom-text-only', ('zoom-text-only',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"Specifies whether the zoom factor on a frame applies only to the " "Whether the zoom factor on a frame applies only to the text or to "
"text or to all content."), "all content."),
('frame-flattening', ('frame-flattening',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"With this setting each subframe is expanded to its contents. This " "Whether to expand each subframe to its contents.\n\n"
"will flatten all the frames to become one scrollable " "This will flatten all the frames to become one scrollable page."),
"page."),
('frame-flattening',
SettingValue(types.Bool(), 'false'),
"With this setting each subframe is expanded to its contents. This "
"will flatten all the frames to become one scrollable "
"page."),
('user-stylesheet', ('user-stylesheet',
SettingValue(types.WebSettingsFile(), ''), SettingValue(types.WebSettingsFile(), ''),
"User stylesheet to set."), "User stylesheet to use."),
('user-stylesheet',
SettingValue(types.WebSettingsFile(), ''),
"User stylesheet to set."),
('css-media-type', ('css-media-type',
SettingValue(types.String(none_ok=True), ''), SettingValue(types.String(none_ok=True), ''),
"Set the CSS media type."), "Set the CSS media type."),
('css-media-type',
SettingValue(types.String(none_ok=True), ''),
"Set the CSS media type."),
#('accelerated-compositing',
# SettingValue(types.Bool(), 'true'),
# "This feature, when used in conjunction with QGraphicsWebView, "
# "accelerates animations of web content. CSS animations of the "
# "transform and opacity properties will be rendered by composing the "
# "cached content of the animated elements."),
#('tiled-backing-store',
# SettingValue(types.Bool(), 'false'),
# "This setting enables the tiled backing store feature for a "
# "QGraphicsWebView. With the tiled backing store enabled, the web "
# "page contents in and around the current visible area is "
# "speculatively cached to bitmap tiles. The tiles are automatically "
# "kept in sync with the web page as it changes. Enabling tiling can "
# "significantly speed up painting heavy operations like scrolling. "
# "Enabling the feature increases memory consuption."),
)), )),
('network', sect.KeyValue( ('network', sect.KeyValue(
('do-not-track', ('do-not-track',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Value to send in the DNT header."), "Value to send in the `DNT` header."),
('accept-language', ('accept-language',
SettingValue(types.String(none_ok=True), 'en-US,en'), SettingValue(types.String(none_ok=True), 'en-US,en'),
"Value to send in the accept-language header."), "Value to send in the `accept-language` header."),
('user-agent', ('user-agent',
SettingValue(types.String(none_ok=True), ''), SettingValue(types.String(none_ok=True), ''),
@ -320,7 +296,9 @@ DATA = OrderedDict([
('proxy', ('proxy',
SettingValue(types.Proxy(), 'system'), SettingValue(types.Proxy(), 'system'),
"The proxy to use."), "The proxy to use.\n\n"
"In addition to the listed values, you can use a `socks://...` or "
"`http://...` URL."),
('ssl-strict', ('ssl-strict',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
@ -328,14 +306,13 @@ DATA = OrderedDict([
('dns-prefetch', ('dns-prefetch',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Specifies whether QtWebkit will try to pre-fetch DNS entries to " "Whether to try to pre-fetch DNS entries to speed up browsing."),
"speed up browsing."),
)), )),
('completion', sect.KeyValue( ('completion', sect.KeyValue(
('show', ('show',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Whether to show the autocompletion window or not."), "Whether to show the autocompletion window."),
('height', ('height',
SettingValue(types.PercOrInt(minperc=0, maxperc=100, minint=1), SettingValue(types.PercOrInt(minperc=0, maxperc=100, minint=1),
@ -345,8 +322,8 @@ DATA = OrderedDict([
('history-length', ('history-length',
SettingValue(types.Int(minval=-1), '100'), SettingValue(types.Int(minval=-1), '100'),
"How many commands to save in the history. 0: no history / -1: " "How many commands to save in the history.\n\n"
"unlimited"), "0: no history / -1: unlimited"),
('quick-complete', ('quick-complete',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
@ -384,15 +361,18 @@ DATA = OrderedDict([
('spatial-navigation', ('spatial-navigation',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"Enables or disables the Spatial Navigation feature, which consists " "Enables or disables the Spatial Navigation feature\n\n"
"in the ability to navigate between focusable elements in a Web " "Spatial navigation consists in the ability to navigate between "
"page, such as hyperlinks and form controls, by using Left, Right, " "focusable elements in a Web page, such as hyperlinks and form "
"Up and Down arrow keys."), "controls, by using Left, Right, Up and Down arrow keys. For "
"example, if a user presses the Right key, heuristics determine "
"whether there is an element he might be trying to reach towards the "
"right and which element he probably wants."),
('links-included-in-focus-chain', ('links-included-in-focus-chain',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Specifies whether hyperlinks should be included in the keyboard " "Whether hyperlinks should be included in the keyboard focus "
"focus chain."), "chain."),
)), )),
('tabbar', sect.KeyValue( ('tabbar', sect.KeyValue(
@ -448,14 +428,26 @@ DATA = OrderedDict([
('maximum-pages-in-cache', ('maximum-pages-in-cache',
SettingValue(types.Int(none_ok=True, minval=0, maxval=MAXVALS['int']), SettingValue(types.Int(none_ok=True, minval=0, maxval=MAXVALS['int']),
''), ''),
"Sets the maximum number of pages to hold in the memory page cache."), "The maximum number of pages to hold in the memory page cache.\n\n"
"The Page Cache allows for a nicer user experience when navigating "
"forth or back to pages in the forward/back history, by pausing and "
"resuming up to _n_ pages.\n\n"
"For more information about the feature, please refer to: "
"http://webkit.org/blog/427/webkit-page-cache-i-the-basics/"),
('object-cache-capacities', ('object-cache-capacities',
SettingValue(types.WebKitBytesList(length=3, maxsize=MAXVALS['int']), SettingValue(types.WebKitBytesList(length=3, maxsize=MAXVALS['int']),
''), ''),
"Specifies the capacities for the memory cache for dead objects " "The capacities for the memory cache for dead objects such as "
"such as stylesheets or scripts. Three values are expected: " "stylesheets or scripts. Syntax: cacheMinDeadCapacity, cacheMaxDead, "
"cacheMinDeadCapacity, cacheMaxDead, totalCapacity."), "totalCapacity.\n\n"
"The _cacheMinDeadCapacity_ specifies the minimum number of bytes "
"that dead objects should consume when the cache is under "
"pressure.\n\n"
"_cacheMaxDead_ is the maximum number of bytes that dead objects "
"should consume when the cache is *not* under pressure.\n\n"
"_totalCapacity_ specifies the maximum number of bytes "
"that the cache should consume *overall*."),
('offline-storage-default-quota', ('offline-storage-default-quota',
SettingValue(types.WebKitBytes(maxsize=MAXVALS['int64']), ''), SettingValue(types.WebKitBytes(maxsize=MAXVALS['int64']), ''),
@ -467,37 +459,38 @@ DATA = OrderedDict([
('offline-storage-database', ('offline-storage-database',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Specifies whether support for the HTML 5 offline storage feature is " "Whether support for the HTML 5 offline storage feature is enabled."),
"enabled or not."),
('offline-web-application-storage', ('offline-web-application-storage',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Specifies whether support for the HTML 5 web application cache " "Whether support for the HTML 5 web application cache feature is "
"feature is enabled or not."), "enabled.\n\n"
"An application cache acts like an HTTP cache in some sense. For "
"documents that use the application cache via JavaScript, the loader "
"engine will first ask the application cache for the contents, "
"before hitting the network.\n\n"
"The feature is described in details at: "
"http://dev.w3.org/html5/spec/Overview.html#appcache"),
('local-storage', ('local-storage',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Specifies whether support for the HTML 5 local storage feature is " "Whether support for the HTML 5 local storage feature is enabled."),
"enabled or not."),
)), )),
('permissions', sect.KeyValue( ('permissions', sect.KeyValue(
('allow-images', ('allow-images',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Specifies whether images are automatically loaded in web pages."), "Whether images are automatically loaded in web pages."),
('allow-javascript', ('allow-javascript',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Enables or disables the running of JavaScript programs."), "Enables or disables the running of JavaScript programs."),
#('allow-java',
# SettingValue(types.Bool(), 'true'),
# "Enables or disables Java applets. Currently Java applets are "
# "not supported"),
('allow-plugins', ('allow-plugins',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"Enables or disables plugins in Web pages."), "Enables or disables plugins in Web pages.\n\n"
'Qt plugins with a mimetype such as "application/x-qt-plugin" are '
"not affected by this setting."),
('allow-javascript', ('allow-javascript',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
@ -514,26 +507,25 @@ DATA = OrderedDict([
('javascript-can-open-windows', ('javascript-can-open-windows',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"Specifies whether JavaScript programs can open new windows."), "Whether JavaScript programs can open new windows."),
('javascript-can-close-windows', ('javascript-can-close-windows',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"Specifies whether JavaScript programs can close windows."), "Whether JavaScript programs can close windows."),
('javascript-can-access-clipboard', ('javascript-can-access-clipboard',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"Specifies whether JavaScript programs can read or write to the " "Whether JavaScript programs can read or write to the clipboard."),
"clipboard."),
('local-content-can-access-remote-urls', ('local-content-can-access-remote-urls',
SettingValue(types.Bool(), 'false'), SettingValue(types.Bool(), 'false'),
"Specifies whether locally loaded documents are allowed to access " "Whether locally loaded documents are allowed to access remote "
"remote urls."), "urls."),
('local-content-can-access-file-urls', ('local-content-can-access-file-urls',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Specifies whether locally loaded documents are allowed to access " "Whether locally loaded documents are allowed to access other local "
"other local urls."), "urls."),
('cookies-accept', ('cookies-accept',
SettingValue(types.AcceptCookies(), 'default'), SettingValue(types.AcceptCookies(), 'default'),
@ -542,7 +534,6 @@ DATA = OrderedDict([
('cookies-store', ('cookies-store',
SettingValue(types.Bool(), 'true'), SettingValue(types.Bool(), 'true'),
"Whether to store cookies."), "Whether to store cookies."),
)), )),
('hints', sect.KeyValue( ('hints', sect.KeyValue(
@ -771,7 +762,7 @@ DATA = OrderedDict([
('completion.bg', ('completion.bg',
SettingValue(types.QssColor(), '#333333'), SettingValue(types.QssColor(), '#333333'),
"Text color of the completion widget."), "Background color of the completion widget."),
('completion.item.bg', ('completion.item.bg',
SettingValue(types.QssColor(), '${completion.bg}'), SettingValue(types.QssColor(), '${completion.bg}'),

9
qutebrowser/config/conftypes.py
View File

@ -455,7 +455,7 @@ class ColorSystem(BaseType):
valid_values = ValidValues(('rgb', "Interpolate in the RGB color system."), valid_values = ValidValues(('rgb', "Interpolate in the RGB color system."),
('hsv', "Interpolate in the HSV color system."), ('hsv', "Interpolate in the HSV color system."),
('hsl', "Interpolate in the HSV color system.")) ('hsl', "Interpolate in the HSL color system."))
def validate(self, value): def validate(self, value):
super().validate(value.lower()) super().validate(value.lower())
@ -742,7 +742,8 @@ class HintMode(BaseType):
"""Base class for the hints -> mode setting.""" """Base class for the hints -> mode setting."""
valid_values = ValidValues(('number', "Use numeric hints."), valid_values = ValidValues(('number', "Use numeric hints."),
('letter', "Use the chars in hints -> chars.")) ('letter', "Use the chars in the hints -> chars "
"setting."))
class Proxy(BaseType): class Proxy(BaseType):
@ -899,7 +900,7 @@ class LastClose(BaseType):
"""Behaviour when the last tab is closed.""" """Behaviour when the last tab is closed."""
valid_values = ValidValues(('ignore', "Don't do anything."), valid_values = ValidValues(('ignore', "Don't do anything."),
('blank', "Load about:blank."), ('blank', "Load a blank page."),
('quit', "Quit qutebrowser.")) ('quit', "Quit qutebrowser."))
@ -907,7 +908,7 @@ class AcceptCookies(BaseType):
"""Whether to accept a cookie.""" """Whether to accept a cookie."""
valid_values = ValidValues(('default', "Default QtWebKit behaviour"), valid_values = ValidValues(('default', "Default QtWebKit behaviour."),
('never', "Don't accept cookies at all.")) ('never', "Don't accept cookies at all."))