[PATCH] docs: improve issue tracker integration docs

[Thomas De Schampheleire]

Hi Andrew,

On Wed, Feb 25, 2015 at 2:06 PM, Andrew Shadura <andrew at shadura.me> wrote:
> # HG changeset patch
> # User Andrew Shadura <andrew at shadura.me>
> # Date 1424869587 -3600
> #      Wed Feb 25 14:06:27 2015 +0100
> # Node ID 5b85679c832b1de3471ed3c62a555d22cbad0c33
> # Parent  54ca0422017d790f16135b4da347850c68458c55
> docs: improve issue tracker integration docs
>
> diff --git a/docs/setup.rst b/docs/setup.rst
> --- a/docs/setup.rst
> +++ b/docs/setup.rst
> @@ -448,16 +448,29 @@ uncomment following variables in the ini
>      issue_prefix = #
>
>  `issue_pat` is the regular expression that will fetch issues from commit messages.

Maybe this sentence could be changed as well, something like:

`issue_pat` is the regular expression describing which strings in
commit messages will be treated as issue references. A match group in
parentheses should be used to specify the actual issue id.

> -Default regex will match issues in format of #<number> eg. #300.
> +Default regex matches issues in format of #<number> eg. #300.

I would say:

The default expression matches issues in the format '#<number>', e.g. '#300'.

>
> -Matched issues will be replace with the link specified as `issue_server_link`
> -{id} will be replaced with issue id, and {repo} with repository name.
> -Since the # is striped `issue_prefix` is added as a prefix to url.
> -`issue_prefix` can be something different than # if you pass
> -ISSUE- as issue prefix this will generate an url in format::
> +Matched issues are be replaced with the link specified as `issue_server_link`

are be --> are

> +{id} is replaced with issue id, and {repo} with repository name.

with the issue id
with the repository name

> +Since the # is stripped away, `issue_prefix` is added as a prefix to url.

'to url' is not very clear: the prefix is added to the text of the
link, not the url itself. So maybe:

.... is added as a prefix to the link text.

> +`issue_prefix` doesn't necessarily need to be #, so if you set issue

I would replace the comma with a colon (:) and then remove the 'so'

> +prefix to ISSUE- this will generate an URL in format::

an URL -> a URL since URL is pronounced 'you-are-el'

>
>    <a href="https://myissueserver.com/example_repo/issue/300">ISSUE-300</a>
>
> +If needed, more than one pattern can be specified by appending a unique suffix to
> +the variables. For example::
> +
> +    issue_pat_wiki = (?:wiki-)(.+)
> +    issue_server_link_wiki = https://mywiki.com/{id}
> +    issue_prefix_wiki = WIKI-
> +
> +From now on, wiki pages can be referenced as wiki-some-id, and every such reference

'From now on' -> 'With these settings'

> +will be transformed into::
> +
> +  <a href="https://mywiki.com/some-id">WIKI-some-id</a>
> +
> +

Best regards,
Thomas