Convert demo READMEs to Sphinx index pages

[huonw]

This moves us towards using Read the Docs as the main source of demos, by duplicating the indexing information from READMEs into the Sphinx docs.

We've decided to move to using Read the Docs like this because:

• it gives us more control over how things are shown (e.g. Hide generated notebook cells from Sphinx output #1386)
• the display is faster
• it allows us to version properly, including with internal links to documentation of the same version as the demo

I used m2r to convert each of our demo READMEs to a reStructuredText index.txt file, and then fixed them up by hand. For each index, I've gone with:

Title
======

... description with subsections etc ...

Table of contents
------------------

... full ToC listing of subfolders/demos of this index ...

(Where the description is empty in some cases, for directories without READMEs: #1139.)

The thinking is we'll replace the README.md files with a much simplified set of information, potentially just a link to the corresponding Read the Docs. However, the READMEs are still useful as an index if someone has a copy of the demos locally in Jupyter lab. Thus, this PR also extends the demo_table.py script to render the demo indexing table to both a raw-HTML markdown version into demos/README.md and a rST list-table version into docs/demos/index.txt. This means we can still retain that demo table in an otherwise reduced/not-human-maintained demos/README.md.

Other than extending demo_table.py, this tries to do the minimal work to get this working. Future work:

• optimising the display of each of the tables (at the moment they scroll sideways a lot): Read the Docs demo tables involve a lot of sideways scrolling #1418
• handling abbreviations in the main indexing table, because it doesn't seem easy to get hover text in rST: Read the Docs demo index tables have abbreviations without explanation #1417
• validating links (likely covered by Many sphinx warnings from demos #1360)
• updating the demos to have relative links pointing to the index files, not README.mds (likely covered by Demos in readthedocs have broken links #1292 and Many sphinx warnings from demos #1360)
• updating the README files to remove their content: demo READMEs duplicate all of the Read the Docs content #1419
• updating any links to the demos on GitHub to point to Read the Docs: Links to demos should point to Read the Docs #1420

Rendered demo landing page: https://stellargraph--1391.org.readthedocs.build/en/1391/demos/index.html

See: #1298

[codeclimate]

Code Climate has analyzed commit 41165d4 and detected 5 issues on this pull request.

Here's the issue category breakdown:

Category	Count
Complexity	1
Security	4

View more on Code Climate.

[codeclimate]

Avoid deeply nested control flow statements.

[codeclimate]

Use of assert detected. The enclosed code will be removed when compiling to optimised byte code.

[timpitman]

This is looking good - the index files for the different demo folders looked correct. On the overall demo index (https://stellargraph--1391.org.readthedocs.build/en/1391/demos/index.html) , the table doesn't have hover hints, so is a bit hard to read - do we need longer names for the headings again?

[kieranricardo]

The index.txt files look good to me 👍

[huonw]

do we need longer names for the headings again?

Yeah, I'm going to open a follow up issue covering this and other bits from the PR description:

• optimising the display of each of the tables (at the moment they scroll sideways a lot)
• handling abbreviations in the main indexing table, because it doesn't seem easy to get hover text in rST
• updating the README files to remove their content
• updating any links to the demos on GitHub to point to Read the Docs

(The other future work there should be handled by other issues.)

[huonw]

I opened #1417, #1418, #1419, #1420.