Using sphinx.ext.extlinks for issue links#

Datasette’s release notes are formatted using Sphinx. Almost every bullet point links to the corresponding GitHub issue, so they were full of lines that look like this:

- Fixed a bug where ``?_search=`` and ``?_sort=`` parameters were incorrectly duplicated when the filter form on the table page was re-submitted. (`#1214 <https://github.com/simonw/datasette/issues/1214>`__)

I noticed that the aspw documentation was using sphinx.ext.extlinks to define a macro for this: :issue:`268` - so I decided to configure that for Datasette.

I added the following to the conf.py for my documentation:

1
extensions = ["sphinx.ext.extlinks"]
2

3
extlinks = {
4
    "issue": ("https://github.com/simonw/datasette/issues/%s", "#"),
5
}

Then in Visual Studio Code I opened the “Edit -> Replace in Files” tool. I used this search pattern:

1
`#(\d+) <https://github.com/simonw/datasette/issues/\1>`__

And this as the replacement value:

1
:issue:`$1`

Note that the search pattern uses \1 as the group reference for the captured number, but in the replacement value you use $1 to re-use that value.

Here’s the commit where I applied that change to Datasette’s existing documentation.