CONTRIBUTING.rst has broken links when viewed on GitHub

[pushfoo]

Bug Report

tl;dr :ref:s and other directives don't seem to render in a GitHub view of an .rst file, even for targets within the same file

System Info

Version 117.0.5938.62 (Official Build) built on Debian 11.7, running on Debian 11.6 (64-bit)

Actual behavior:

The Testing link in After making changes does not link anywhere and does not render correctly:

Expected behavior:

The Testing link in After making changes:

1. Works when clicked
2. (Ideally) renders cleanly

Steps to reproduce/example code:

1. Go to After making changes
2. Observe the link
3. Attempt to click it

Correcting the capitalization does not change this either. It appears GitHub cannot render :ref: targets.

Root causes

There seems to be limited post-processing of directives in GitHub views

Implications

This may block #1302 and affect #1886, both of which I was looking at when I noticed this.

Possible ways to fix it

1. Use a script which renders CONTRIBUTING.rst as markdown
2. Go back to old approach: the abbreviated model + links to the web site

I'm not in favor of clever scripts because those will probably break at some point.

[cspotcode]

Go back to old approach: the abbreviated model + links to the web site

It can be more than abbreviated, it can be a single link to the website with zero additional information.

[pushfoo]

I'm ok with that option, but might make it more or less a toctree dump for the relevant pages. @pvcraven any objections? I don't see the value of keeping this page seperate then reaching back through the hierarchy to include it.

[einarf]

Can't we just change README and CONTRIBUTING into markdown files? They don't really need the complexity rst has to offer in the first place.

[Cleptomania]

Actually the CONTRIBUTING file is included directly in the doc build, though it would be trivial to add in MyST Parser extension to sphinx to allow us to just include the Markdown(and maybe use more markdown in the future?)

[einarf]

Why don't we just link to the file instead and make it markdown? That has such a lower complecity. It makes sese that the contribution guidelines are part of the code anyway and not the docs. This is pretty standard in other projects.

[pushfoo]

This seems done. We switched to markdown for the current file.