[docs] Integrate sphinx-issues into the Sphinx config

[shenxianpeng]

closes #12551

1. removed extlinks of issue and pull, only left pypi because sphinx-issues not support role pypi now, but I have created Add new role :pypi: sloria/sphinx-issues#145 to let it supports
2. changed pull to pr in NEWS.rst to fix the error NEWS.rst:3614: ERROR: Unknown interpreted text role "pull".

[webknjaz]

only left pypi because sphinx-issues not support role pypi now, but I have created Add new role :pypi: sloria/sphinx-issues#145 to let it supports

I have a feeling that request will be rejected as being out of the scope. The extension seems to be focused on the issue trackers.

[shenxianpeng]

I feel the same. It would be more widely applicable if it could be changed to sphinx-links or similar, but I don't think that's possible.

[shenxianpeng]

My pull request sloria/sphinx-issues#145 to support role pypi has been accepted and is available in the latest release of sphinx-issues (v4.1.0), so I removed the last extlinks from conf.py.

[shenxianpeng]

Now it's ready for review.

[ichard26]

I'm not convinced that it's worth the extra dependency (granted it's tiny) to remove only a few lines of static Sphinx configuration, but I suppose standardization of the role names (and any new ones) could be a benefit?

I'll note that issues_pr_prefix = "PR #" is needed to match the pre-existing behaviour 100%.

Ultimately I'm neutral on the change.

[webknjaz]

@ichard26 yes, standardization is key. Plus, it's one thing less to copy over through many projects for people who tend to maintain many and sync them periodically. It also exposes a few other roles for free.

[webknjaz]

@shenxianpeng now that you removed the entire setting, could you also drop the extension from the extensions variable so it's not even loaded?

[shenxianpeng]

@webknjaz I have dropped sphinx.ext.extlinks from extensions in commit babf447

[webknjaz]

@pradyunsg easy merge?

[webknjaz]

FYI, trivial fragments aren't displayed anywhere, and their content is disregarded. The contribution guidelines state that they should be empty (but this isn't linted for some reason). This is a way to fool the checks, but it doesn't let one actually tell the end-users what's happened/changed.

I believe that once #12853 is in, it'll be possible to move this to one of packaging/contrib/misc if desired.

[webknjaz]

By the way, if it's decided that this should go to a change log, it should probably link the integrated project with a hyperlink.

[webknjaz]

@pradyunsg easy merge?

[webknjaz]

@sbidoul easy merge?

[pradyunsg]

(thanks @ichard26!)

[ichard26]

You're welcome!