kallithea: docs/setup.rst comparison

comparison docs/setup.rst @ 7230:d24051ce961c

issues: support generic regex replacements in issue_url and issue_prefix Issue reference linking is pretty limited: - the issue_url is a literal with only three special tokens {id}, {repo} and {repo_name}. There is no way to let the URL be dependent on other elements of the input issue reference. - The value for {id} is somewhat oddly determined by the concatenation of all parenthesized groups in the issue_pat regular expression - the link text of the resulting link is limited to the contents of the literal issue_prefix with the determined {id}. It is not possible to retain the input issue reference verbatim, nor to let the link text be dependent on other elements of the input issue reference. This commit makes the issue reference linking more flexible: - issue_prefix is replaced by the more generic issue_sub(stitution), which is a string that may contain backreferences to regex groups specified in issue_pat. This string, with backreferences resolved, is used as the link text of urlified issue references. - if issue_sub is empty, the entire text matched by issue_pat is used as the link text. - like issue_sub, also issue_url can contain backreferences to regex groups. - {id} is no longer treated as a special token, as it can be solved by generic backreferences ('\g<id>' assuming issue pattern contains something like '(P<id>\d+)'. {repo} and {repo_name} are still supported, because their value is provided externally and not normally part of the issue pattern. Documentation and ini file template is updated as well.

author	Thomas De Schampheleire <thomas.de_schampheleire@nokia.com>
date	Sat, 10 Mar 2018 22:01:59 +0100
parents	1969f7dfb6b0
children	9937ae52f167

comparison

equal deleted inserted replaced

-:e5a7f8f41370
+:d24051ce961c
 Integration with issue trackers
 -------------------------------
 Kallithea provides a simple integration with issue trackers. It's possible
 to define a regular expression that will match an issue ID in commit messages,
-and have that replaced with a URL to the issue. To enable this simply
+and have that replaced with a URL to the issue.
-uncomment the following variables in the ini file::
+This is achieved with following three variables in the ini file::
-issue_pat = (?:^#|\s#)(\w+)
-issue_server_link = https://issues.example.com/{repo}/issue/{id}
+issue_pat = #(\d+)
-issue_prefix = #
+issue_server_link = https://issues.example.com/{repo}/issue/\1
+issue_sub =
 ``issue_pat`` is the regular expression describing which strings in
-commit messages will be treated as issue references. A match group in
+commit messages will be treated as issue references. The expression can/should
-parentheses should be used to specify the actual issue id.
+have one or more parenthesized groups that can later be referred to in
+``issue_server_link`` and ``issue_sub`` (see below). If you prefer, named groups
-The default expression matches issues in the format ``#<number>``, e.g., ``#300``.
+can be used instead of simple parenthesized groups.
+If the pattern should only match if it is preceded by whitespace, add the
+following string before the actual pattern: ``(?:^|(?<=\s))``.
+If the pattern should only match if it is followed by whitespace, add the
+following string after the actual pattern: ``(?:$|(?=\s))``.
+These expressions use lookbehind and lookahead assertions of the Python regular
+expression module to avoid the whitespace to be part of the actual pattern,
+otherwise the link text will also contain that whitespace.
 Matched issue references are replaced with the link specified in
-``issue_server_link``. ``{id}`` is replaced with the issue ID, and
+``issue_server_link``, in which any backreferences are resolved. Backreferences
-``{repo}`` with the repository name.  Since the # is stripped away,
+can be ``\1``, ``\2``, ... or for named groups ``\g<groupname>``.
-``issue_prefix`` is prepended to the link text.  ``issue_prefix`` doesn't
+The special token ``{repo}`` is replaced with the full repository path
-necessarily need to be ``#``: if you set issue prefix to ``ISSUE-`` this will
+(including repository groups), while token ``{repo_name}`` is replaced with the
-generate a URL in the format:
+repository name (without repository groups).
+The link text is determined by ``issue_sub``, which can be a string containing
+backreferences to the groups specified in ``issue_pat``. If ``issue_sub`` is
+empty, then the text matched by ``issue_pat`` is used verbatim.
+The example settings shown above match issues in the format ``#<number>``.
+This will cause the text ``#300`` to be transformed into a link:
 .. code-block:: html
-<a href="https://issues.example.com/example_repo/issue/300">ISSUE-300</a>
+<a href="https://issues.example.com/example_repo/issue/300">#300</a>
+The following example transforms a text starting with either of 'pullrequest',
+'pull request' or 'PR', followed by an optional space, then a pound character
+(#) and one or more digits, into a link with the text 'PR #' followed by the
+digits::
+issue_pat = (pullrequest|pull request|PR) ?#(\d+)
+issue_server_link = https://issues.example.com/\2
+issue_sub = PR #\2
+The following example demonstrates how to require whitespace before the issue
+reference in order for it to be recognized, such that the text ``issue#123`` will
+not cause a match, but ``issue #123`` will::
+issue_pat = (?:^|(?<=\s))#(\d+)
+issue_server_link = https://issues.example.com/\1
+issue_sub =
 If needed, more than one pattern can be specified by appending a unique suffix to
-the variables. For example::
+the variables. For example, also demonstrating the use of named groups::
-issue_pat_wiki = (?:wiki-)(.+)
+issue_pat_wiki = wiki-(?P<pagename>\S+)
-issue_server_link_wiki = https://wiki.example.com/{id}
+issue_server_link_wiki = https://wiki.example.com/\g<pagename>
-issue_prefix_wiki = WIKI-
+issue_sub_wiki = WIKI-\g<pagename>
 With these settings, wiki pages can be referenced as wiki-some-id, and every
 such reference will be transformed into:
 .. code-block:: html
 <a href="https://wiki.example.com/some-id">WIKI-some-id</a>
+Refer to the `Python regular expression documentation`_ for more details about
+the supported syntax in ``issue_pat``, ``issue_server_link`` and ``issue_sub``.
 Hook management
 ---------------
 .. __: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ .
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
 .. _python: http://www.python.org/
+.. _Python regular expression documentation: https://docs.python.org/2/library/re.html
 .. _Mercurial: https://www.mercurial-scm.org/
 .. _Celery: http://celeryproject.org/
 .. _Celery documentation: http://docs.celeryproject.org/en/latest/getting-started/index.html
 .. _RabbitMQ: http://www.rabbitmq.com/
 .. _Redis: http://redis.io/

Mercurial > kallithea

comparison docs/setup.rst @ 7230:d24051ce961c