opendev/gerrit
Code Issues Proposed changes

Merge changes I3cdd65fb,Ie78ae347

Browse Source 
* changes:
  Fix asciidoc formatting in JS API documentation
  Tidy up formatting in authentication documentation
This commit is contained in:
Shawn Pearce 2013-08-01 17:26:06 +00:00 committed by Gerrit Code Review
commit f85f896bdd
2 changed files with 65 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
Documentation/config-gerrit.txt
View File

@ -140,7 +140,7 @@ it then verifies by performing a simple bind against the configured
<<ldap.server,ldap.server>>. In this configuration the web server
is not involved in the user authentication process.
+
Unlike LDAP above, the username used to perform the LDAP simple bind
Unlike `LDAP` above, the username used to perform the LDAP simple bind
request is the exact string supplied by in the dialog by the user.
The configured <<ldap.username,ldap.username>> identity is not used to obtain
account information.
@ -165,7 +165,7 @@ By default, OpenID.
+
List of permitted OpenID providers. A user may only authenticate
with an OpenID that matches this list. Only used if `auth.type`
is set to OpenID (the default).
is set to `OpenID` (the default).
+
Patterns may be either a
link:http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html[standard
@ -178,7 +178,7 @@ allowing users to authenticate with any OpenID provider.
[[auth.trustedOpenID]]auth.trustedOpenID::
+
List of trusted OpenID providers. Only used if `auth.type` is
set to OpenID (the default).
set to `OpenID` (the default).
+
In order for a user to take advantage of permissions beyond those
granted to the `Anonymous Users` and `Registered Users` groups,
@ -196,7 +196,7 @@ allowing Gerrit to trust any OpenID it receives.
[[auth.openIdDomain]]auth.openIdDomain::
+
List of allowed OpenID email address domains. Only used if
`auth.type` is set to "OPENID" or "OPENID_SSO".
`auth.type` is set to `OPENID` or `OPENID_SSO`.
+
Domain is case insensitive and must be in the same form as it
appears in the email address, for example, "example.com".
@ -245,35 +245,36 @@ Default is 12 hours.
[[auth.openIdSsoUrl]]auth.openIdSsoUrl::
+
The SSO entry point URL. Only used if `auth.type` was set to
OpenID_SSO.
The SSO entry point URL. Only used if `auth.type` is set to
`OpenID_SSO`.
+
The "Sign In" link will send users directly to this URL.
[[auth.httpHeader]]auth.httpHeader::
+
HTTP header to trust the username from, or unset to select HTTP basic
or digest authentication. Only used if `auth.type` is set to HTTP.
or digest authentication. Only used if `auth.type` is set to `HTTP`.
[[auth.loginUrl]]auth.loginUrl::
+
URL to redirect a browser to after the end-user has clicked on the
login link in the upper right corner. Only used if 'auth.type' was set
to HTTP or HTTP_LDAP.
login link in the upper right corner. Only used if `auth.type` is set
to `HTTP` or `HTTP_LDAP`.
Organizations using an enterprise single-sign-on solution may want to
redirect the browser to the SSO product's sign-in page for completing the
login process and validate their credentials.
+
If set, Gerrit allows to access anonymously until the end-user performs the login
and then provides a trusted identity through the HTTP header.
If set, Gerrit allows anonymous access until the end-user performs the login
and provides a trusted identity through the HTTP header.
If not set, Gerrit requires the HTTP header with a trusted identity
otherwise returns the error page LoginRedirect.html.
and returns the error page 'LoginRedirect.html' if such a header is not
present.
[[auth.loginText]]auth.loginText::
+
Text displayed in the loginUrl link. Only used if 'auth.loginUrl' was set.
Text displayed in the loginUrl link. Only used if `auth.loginUrl` is set.
+
If not set, the 'Sign In' text is used.
If not set, the "Sign In" text is used.
[[auth.logoutUrl]]auth.logoutUrl::
+
@ -287,14 +288,14 @@ If not set, the redirect returns to the list of all open changes.
[[auth.registerUrl]]auth.registerUrl::
+
Target for the "Register" link in the upper right corner. Used only
when auth.type is `LDAP`.
when `auth.type` is `LDAP`.
+
If not set, no "Register" link is displayed.
[[auth.registerText]]auth.registerText::
+
Text for the "Register" link in the upper right corner. Used only
when auth.type is `LDAP`.
when `auth.type` is `LDAP`.
+
If not set, defaults to "Register".
@ -305,7 +306,7 @@ full name.
[[auth.httpPasswordUrl]]auth.httpPasswordUrl::
+
Target for the "Obtain Password" link. Used only when auth.type is
Target for the "Obtain Password" link. Used only when `auth.type` is
`LDAP`, `LDAP_BIND` or `CUSTOM_EXTENSION`.
+
@ -325,7 +326,7 @@ By default, false.
[[auth.emailFormat]]auth.emailFormat::
+
Optional format string to construct user email addresses out of
user login names. Only used if auth.type is `HTTP`, `HTTP_LDAP`
user login names. Only used if `auth.type` is `HTTP`, `HTTP_LDAP`
or `LDAP`.
+
This value can be set to a format string, where `{0}` is replaced
@ -1711,7 +1712,7 @@ Failing to load the Filter class would result in a Gerrit start-up
failure, as this class is supposed to provide mandatory filtering
in front of Gerrit HTTP protocol.
+
Typical usage is in conjunction with the auth.type=HTTP as replacement
Typical usage is in conjunction with the `auth.type=HTTP` as replacement
of an Apache HTTP proxy layer as security enforcement on top of Gerrit
by returning a trusted username as HTTP Header.
+
@ -1733,7 +1734,7 @@ a trusted username in the `TRUSTED_USER` HTTP Header:
LDAP integration is only enabled if `auth.type` is set to
`HTTP_LDAP`, `LDAP` or `CLIENT_SSL_CERT_LDAP`. See above for a
detailed description of the auth.type settings and their
detailed description of the `auth.type` settings and their
implications.
An example LDAP configuration follows, and then discussion of
@ -1762,7 +1763,7 @@ URL of the organization's LDAP server to query for user information
and group membership from. Must be of the form `ldap://host` or
`ldaps://host` to bind with either a plaintext or SSL connection.
+
If auth.type is `LDAP` this setting should use `ldaps://` to
If `auth.type` is `LDAP` this setting should use `ldaps://` to
ensure the end user's plaintext password is transmitted only over
an encrypted connection.
@ -1824,9 +1825,9 @@ Default is `subtree` as many directories have several levels.
+
Query pattern to use when searching for a user account. This may be
any valid LDAP query expression, including the standard `(&...)` and
`(|...)` operators. If auth.type is `HTTP_LDAP` then the variable
`(|...)` operators. If `auth.type` is `HTTP_LDAP` then the variable
`${username}` is replaced with a parameter set to the username
that was supplied by the HTTP server. If auth.type is `LDAP` then
that was supplied by the HTTP server. If `auth.type` is `LDAP` then
the variable `${username}` is replaced by the string entered by
the end user.
+
@ -1938,7 +1939,7 @@ Query pattern to use when searching for the groups that a user
account is currently a member of. This may be any valid LDAP query
expression, including the standard `(&...)` and `(|...)` operators.
+
If auth.type is `HTTP_LDAP` then the variable `${username}` is
If `auth.type` is `HTTP_LDAP` then the variable `${username}` is
replaced with a parameter set to the username that was supplied
by the HTTP server. Other variables appearing in the pattern,
such as `${fooBarAttribute}`, are replaced with the value of the

80
Documentation/js-api.txt
View File

@ -26,7 +26,7 @@ Plugin Instance
The plugin instance is passed to the plugin's initialization function
and provides a number of utility services to plugin authors.
[[self.delete]]
[[self_delete]]
self.delete()
~~~~~~~~~~~~~
Issues a DELETE REST API request to the Gerrit server.
@ -43,7 +43,7 @@ Gerrit.delete(url, callback)
JSON result of the API call. DELETE methods often return
`204 No Content`, which is passed as null.
[[self.get]]
[[self_get]]
self.get()
~~~~~~~~~~
Issues a GET REST API request to the Gerrit server.
@ -61,14 +61,14 @@ self.get(url, callback)
a string, otherwise the result is a JavaScript object or array,
as described in the relevant REST API documentation.
[[self.getPluginName]]
[[self_getPluginName]]
self.getPluginName()
~~~~~~~~~~~~~~~~~~~~
Returns the name this plugin was installed as by the server
administrator. The plugin name is required to access REST API
views installed by the plugin, or to access resources.
[[self.post]]
[[self_post]]
self.post()
~~~~~~~~~~~
Issues a POST REST API request to the Gerrit server.
@ -95,7 +95,7 @@ self.post(
function (r) {});
----
[[self.put]]
[[self_put]]
self.put()
~~~~~~~~~~
Issues a PUT REST API request to the Gerrit server.
@ -122,7 +122,7 @@ self.put(
function (r) {});
----
[[self.onAction]]
[[self_onAction]]
self.onAction()
~~~~~~~~~~~~~~~
Register a JavaScript callback to be invoked when the user clicks
@ -143,11 +143,11 @@ Gerrit.onAction(type, view_name, callback);
* callback: JavaScript function to invoke when the user clicks. The
function will be passed a link:#ActionContext[action context].
[[self.url]]
[[self_url]]
self.url()
~~~~~~~~~~
Returns a URL within the plugin's URL space. If invoked with no
parameter the the URL of the plugin is returned. If passed a string
parameter the URL of the plugin is returned. If passed a string
the argument is appended to the plugin URL.
----
@ -164,14 +164,14 @@ each time the associated action button is clicked by the user. A
context is initialized with sufficient state to issue the associated
REST API RPC.
[[context.action]]
[[context_action]]
context.action
~~~~~~~~~~~~~~
A link:rest-api-changes.html#action-info[ActionInfo] object instance
supplied by the server describing the UI button the user used to
invoke the action.
[[context.call]]
[[context_call]]
context.call()
~~~~~~~~~~~~~~
Issues the REST API call associated with the action. The HTTP method
@ -199,7 +199,7 @@ context.call(
});
----
[[context.change]]
[[context_change]]
context.change
~~~~~~~~~~~~~~
When the action is invoked on a change a
@ -207,7 +207,7 @@ link:rest-api-changes.html#change-info[ChangeInfo] object instance
describing the change. Available fields of the ChangeInfo may vary
based on the options used by the UI when it loaded the change.
[[context.delete]]
[[context_delete]]
context.delete()
~~~~~~~~~~~~~~~~
Issues a DELETE REST API call to the URL associated with the action.
@ -225,7 +225,7 @@ context.delete(callback)
context.delete(function () {});
----
[[context.get]]
[[context_get]]
context.get()
~~~~~~~~~~~~~
Issues a GET REST API call to the URL associated with the action.
@ -246,18 +246,18 @@ context.get(function (result) {
});
----
[[context.go]]
[[context_go]]
context.go()
~~~~~~~~~~~~
Go to a page. Shorthand for link:#Gerrit.go[`Gerrit.go()`].
Go to a page. Shorthand for link:#Gerrit_go[`Gerrit.go()`].
[[context.hide]]
[[context_hide]]
context.hide()
~~~~~~~~~~~~~~
Hide the currently visible popup displayed by
link:#context.popup[`context.popup()`].
link:#context_popup[`context.popup()`].
[[context.post]]
[[context_post]]
context.post()
~~~~~~~~~~~~~~
Issues a POST REST API call to the URL associated with the action.
@ -282,7 +282,7 @@ context.post(
});
----
[[context.popup]]
[[context_popup]]
context.popup()
~~~~~~~~~~~~~~~
@ -290,7 +290,7 @@ Displays a small popup near the activation button to gather
additional input from the user before executing the REST API RPC.
The caller is always responsible for closing the popup with
link#context.hide[`context.hide()`]. Gerrit will handle closing a
link#context_hide[`context.hide()`]. Gerrit will handle closing a
popup if the user presses `Escape` while keyboard focus is within
the popup.
@ -323,7 +323,7 @@ self.onAction('revision', 'start-build', function (c) {
});
----
[[context.put]]
[[context_put]]
context.put()
~~~~~~~~~~~~~
Issues a PUT REST API call to the URL associated with the action.
@ -348,13 +348,13 @@ context.put(
});
----
[[context.refresh]]
[[context_refresh]]
context.refresh()
~~~~~~~~~~~~~~~~~
Refresh the current display. Shorthand for
link:#Gerrit.refresh[`Gerrit.refresh()`].
link:#Gerrit_refresh[`Gerrit.refresh()`].
[[context.revision]]
[[context_revision]]
context.revision
~~~~~~~~~~~~~~~~
When the action is invoked on a specific revision of a change,
@ -404,11 +404,11 @@ The `Gerrit` object is the only symbol provided into the global
namespace by Gerrit Code Review. All top-level functions can be
accessed through this name.
[[Gerrit.delete]]
[[Gerrit_delete]]
Gerrit.delete()
~~~~~~~~~~~~~~~
Issues a DELETE REST API request to the Gerrit server. For plugin
private REST API URLs see link:#self.delete[self.delete()].
private REST API URLs see link:#self_delete[self.delete()].
.Signature
----
@ -428,11 +428,11 @@ Gerrit.delete(
function () {});
----
[[Gerrit.get]]
[[Gerrit_get]]
Gerrit.get()
~~~~~~~~~~~~
Issues a GET REST API request to the Gerrit server. For plugin
private REST API URLs see link:#self.get[self.get()].
private REST API URLs see link:#self_get[self.get()].
.Signature
----
@ -455,18 +455,18 @@ Gerrit.get('/changes/?q=status:open', function (open) {
});
----
[[Gerrit.getPluginName]]
[[Gerrit_getPluginName]]
Gerrit.getPluginName()
~~~~~~~~~~~~~~~~~~~~~~
Returns the name this plugin was installed as by the server
administrator. The plugin name is required to access REST API
views installed by the plugin, or to access resources.
Unlike link:#self.getPluginName[`self.getPluginName()`] this method
Unlike link:#self_getPluginName[`self.getPluginName()`] this method
must guess the name from the JavaScript call stack. Plugins are
encouraged to use `self.getPluginName()` whenever possible.
[[Gerrit.go]]
[[Gerrit_go]]
Gerrit.go()
~~~~~~~~~~~
Updates the web UI to display the view identified by the supplied
@ -480,7 +480,7 @@ If the URL passed matches `http://...`, `https://...`, or `//...`
the current browser window will navigate to the non-Gerrit URL.
The user can return to Gerrit with the back button.
[[Gerrit.install]]
[[Gerrit_install]]
Gerrit.install()
~~~~~~~~~~~~~~~~
Registers a new plugin by invoking the supplied initialization
@ -492,11 +492,11 @@ Gerrit.install(function (self) {
});
----
[[Gerrit.post]]
[[Gerrit_post]]
Gerrit.post()
~~~~~~~~~~~~~
Issues a POST REST API request to the Gerrit server. For plugin
private REST API URLs see link:#self.post[self.post()].
private REST API URLs see link:#self_post[self.post()].
.Signature
----
@ -520,11 +520,11 @@ Gerrit.post(
function (r) {});
----
[[Gerrit.put]]
[[Gerrit_put]]
Gerrit.put()
~~~~~~~~~~~~
Issues a PUT REST API request to the Gerrit server. For plugin
private REST API URLs see link:#self.put[self.put()].
private REST API URLs see link:#self_put[self.put()].
.Signature
----
@ -548,7 +548,7 @@ Gerrit.put(
function (r) {});
----
[[Gerrit.onAction]]
[[Gerrit_onAction]]
Gerrit.onAction()
~~~~~~~~~~~~~~~~~
Register a JavaScript callback to be invoked when the user clicks
@ -569,12 +569,12 @@ Gerrit.onAction(type, view_name, callback);
* callback: JavaScript function to invoke when the user clicks. The
function will be passed a link:#ActionContext[ActionContext].
[[Gerrit.refresh]]
[[Gerrit_refresh]]
Gerrit.refresh()
~~~~~~~~~~~~~~~~
Redisplays the current web UI view, refreshing all information.
[[Gerrit.url]]
[[Gerrit_url]]
Gerrit.url()
~~~~~~~~~~~~
Returns the URL of the Gerrit Code Review server. If invoked with
@ -586,7 +586,7 @@ Gerrit.url(); // "https://gerrit-review.googlesource.com/"
Gerrit.url('/123'); // "https://gerrit-review.googlesource.com/123"
----
For a plugin specific version see link:#self.url()[`self.url()`].
For a plugin specific version see link:#self_url()[`self.url()`].
GERRIT
------