DOC: fix 'Who uses Sphinx-Gallery' list

[StefRe]

the current link in https://sphinx-gallery.github.io/stable/projects_list.html results in 404.

• prevent the project lists in README.rst and projects_list.rst from
  becoming out of sync by putting the projects list in a text file
  to include in both rst files (there were already 2 projects more in
  README.rst than in projects_list.rst)
• fix broken and some permanently redirected links reported by linkcheck

Github markup doesn't allow including files into README.rst, so we must
include from README.rst. Github doesn't process :ref: or :doc: roles
(they are shown literally) so we need to handle the Sphinx Gallery link
separately. The intersphinx links were replaced by ordinary links as
it's very unlikely that these targets would be changed without a
redirect in place.

[lucyleeow]

Could you update it in our README.rst too?

[StefRe]

sorry for the many pushes. build_docs error is unrelated to this PR, see #1017 . It took a while for me to understand the CI now uses sphinx 5.2.0, I used 5.1.1 locally.

[lucyleeow]

Thank you! Just a nit

[StefRe]

hm, the github rst parser seems to not like the :start-after: and :end-before: options, it doesn't include anything see https://github.com/StefRe/sphinx-gallery/tree/fix/who-uses-links, or am I missing something here? Any ideas, @lucyleeow ?

[StefRe]

maybe this is caused by https://github.com/github/markup#github-markup?:

The HTML is sanitized, aggressively removing things that could harm you and your kin—such as script tags, inline-styles, and class or id attributes.

[StefRe]

Changing the order of inclusion doesn't work either as github doesn't process the roles:

[StefRe]

@lucyleeow so I guess I'll have to get back to the original version with the included txt file which isn't ideal but works correctly.

[lucyleeow]

What about just including the whole doc/projects_list.rst file (including the title)? Does the title end up looking weird? Maybe we can amend the title underscore markup?

Thanks again for working on this!

[StefRe]

Up to about 20 mins ago I was convinced that including the complete txt file into README.rst did work correctly but when I now try to reproduce it I can't make it work (see https://github.com/StefRe/sphinx-gallery/tree/fix/test_who-uses-links).

It turns out that including files into rst is blocked for security reasons, see github/markup#172 (comment). Including files into markdown doesn't work either (github/markup#346) and there are obviously no plans to pursue any of this.

I'll try and think of another solution.

[StefRe]

PyPi packages also don't process sphinx extension:

- reStructuredText (without Sphinx extensions)

(the entry for SG uses :ref: to automatically switch between dev and stable, see #754)
(the entries for Scikit-learn and matplotlib use intersphinx links introduced in #819, the advantage is not clear to me (other than maybe if they would change their docs url without a redirect, which is rather unlikely))

[larsoner]

Let's just get rid of :ref: and use HTML links for the README

Also in some packages for RST that will only be included (not rendered alone) I've seen name.inc (for "include") used. It prevents Sphinx from rendering it twice -- once as an "include" in the correct spot, and once as a standalone file where you don't want it.

[StefRe]

This is the best compromise I could achieve: it preserves the :ref: for SG from #754 but reverts the intersphinx links from #819.
The only little blemish is the additional empty line between Sphinx Gallery and the other projects:

in README.rst:

in the docs:

[lucyleeow]

Thanks @StefRe !