Use subn instead of search+sub:

Ack, thanks.

And why do URLs need to be replaced multiple times now?

Because previously I was replacing every words between parenthesis but some can be part of the documentation without being url arguments.
For instance when documenting nested JSON objects like this:

:>json object <swh_pid>: an object whose keys are input persistent
    identifiers and values objects with the following keys:

        * **known (bool)**: whether the object was found

The (bool) string was replaced by an empty one previously.

I am not proud of that s**t but I could not find any other way to do it.

Basically, I just want to concatenate a bullet list to the input data / response data documentation.
self.current_text stores a reference to the latest parsed doc for input data / response data member
but I can not concatenate any string to it without creating a new string reference, so that piece of crap
code.

I think I found a better solution, diff update incoming

That explains the change in regexp, but why the while loop?

Because some url description can have multiple parameters between parenthesis or brackets .

For instance /api/1/content/[(hash_type):](hash)/filetype/ and we want to obtain /api/1/content/filetype/ to reference the endpoint.

Previously, a global replacement was made but now we restrict the replacement to strings starting with :http: and use group capture. So we need to do replacements while a group is captured in the input string.

This would probably deserve a comment explaining that, eg. with that example