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:

extensions = ["sphinx.ext.extlinks"]
extlinks = {
    "issue": ("https://github.com/simonw/datasette/issues/%s", "#"),
}

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

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

And this as the replacement value:

: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.

Related

• vscode Search and replace with regular expressions in VS Code - 2021-08-02
• github Assistance with release notes using GitHub Issues - 2024-08-05
• sphinx Adding Sphinx autodoc to a project, and configuring Read The Docs to build it - 2021-08-10
• readthedocs Promoting the stable version of the documentation using rel=canonical - 2022-01-20
• sphinx literalinclude with markers for showing code in documentation - 2024-01-10
• git git bisect - 2022-10-29
• readthedocs Linking from /latest/ to /stable/ on Read The Docs - 2022-01-20
• datasette Syntax highlighted code examples in Datasette - 2023-07-01
• datasette Redirects for Datasette - 2020-11-25
• readthedocs Using custom Sphinx templates on Read the Docs - 2020-12-07

Created 2021-02-17T17:27:04-08:00 · Edit