POC: Add a simple Sphinx extension to support autolink issues (i.e., #123) in Sphinx

[seisman]

GitHub can automatically convert shorthand references like #1234 into clickable links like #1234. It's very convenient that we don't have to write long Markdown links like

[#1234](https://github.com/GenericMappingTools/pygmt/issues/3361)

Unfortunately, Sphinx doesn't support shorthand references like #1234. In Sphinx, we can use the extlinks extension to define custom roles and reference issues using such ReST syntax :issue:`1234` or MyST Markdown syntax {issue}`1234`, but it's not recognized by GitHub.

Due to the above reasons, we have to configure the change-template of the release-drafter action to:

pygmt/.github/release-drafter.yml

Line 28 in 991cafb

change-template: '* $TITLE ([#$NUMBER]($URL))'

And in our release notes, we have full Markdown links like:

[#1234](https://github.com/GenericMappingTools/pygmt/issues/3361)

which generates long changelog entries like:

* pygmt.project: Add 'output_type' parameter for output in pandas/numpy/file formats ([#3110](https://github.com/GenericMappingTools/pygmt/pull/3110))

This PR adds a simple Sphinx extension (completely written by ChatGPT) to make Sphinx support shorthand references #1234. The extension generally scans the source files, finds the shorthand references (using a regex like #(\d+), and then converts them to full Markdown links. With this extension, shorthand references will work on GitHub and in Sphinx, which can make the changelog entries much shorter and also make it easier to merge multiple entries when we manually polish the release notes.

There are one related StackOverflow question and two unmaintained Sphinx extensions, which motivates me to ask ChatGPT for help:

• https://stackoverflow.com/questions/72424748
• https://github.com/ignatenkobrain/sphinxcontrib-issuetracker
• https://github.com/tony/sphinx-autoissues

The doc/changes.md are converted from full Markdown links into shorthand references, using the following Linux command:

sed -E -i 's/\[#([0-9]+)]\(https:\/\/github.com\/GenericMappingTools\/pygmt\/(issues|pull)\/[0-9]+\)/#\1/g' doc/changes.md

Preview: https://pygmt-dev--3410.org.readthedocs.build/en/3410/changes.html

If agreed, we still need to do:

• Change change-template to '* $TITLE (#$NUMBER)'
• Improve the extension to make it more readable and maintainable

[weiji14]

Feels like quite a bit of code to maintain. Is there not a sphinx plugin to do this? Also, won't this mean we can't just copy and paste the release bot drafter's generated draft changelog to changelog.md?

[seisman]

Is there not a sphinx plugin to do this?

I only found two unmaintained plugins https://github.com/ignatenkobrain/sphinxcontrib-issuetracker and https://github.com/tony/sphinx-autoissues.

Also, won't this mean we can't just copy and paste the release bot drafter's generated draft changelog to changelog.md?

We just need to change the release bot's template

pygmt/.github/release-drafter.yml

Line 28 in c54d72f

change-template: '* $TITLE ([#$NUMBER]($URL))'

to

change-template: '* $TITLE (#$NUMBER)' 

Then, the auto-generated changelog should work in both "GitHub Release Notes" and "changelog.md" without manual edits.

[seisman]

Closing the PR due to the complexity of the sphinx extension and the fact that we only need to update the changelog every three months.