Adopt Sphinx and RTD

[bjlittle]

Would you be willing to adopt sphinx and host on readthedocs ?

The README.rst is pretty large now, and light touch docs could offer a richer source of information to the community.

[Cadair]

Yeah I think our complexity level has crossed the point where "real" docs would be better.

Does matplotlib have a sphinx theme we could use?

[ConorMacBride]

There is mpl-sphinx-theme. The package matplotlib/cheatsheets (https://matplotlib.org/cheatsheets/) might be a good example of how to set this up. Configured here: https://github.com/matplotlib/cheatsheets/blob/master/docs/conf.py.

I think matplotlib have a list of packages they scrape to add the docs to their website so we should check with whoever does that. If it's to be accessible at https://matplotlib.org/pytest-mpl/ we'll probably have to use GitHub Pages or what matplotlib use for hosting.

[tacaswell]

https://github.com/matplotlib/mpl-gui/tree/main/docs might be a better template than the cheatsheets because it is also a library ;)

Matplotlib moved over to self-hosting (for reasons), but it looks like we are already grabbing and hosting what ever is on the gh-pages branch of this repo: matplotlib/matplotlib.org#16

which appears to be 3 pngs for testing (e.g. https://matplotlib.org/pytest-mpl/2.0.x/test_succeeds_remote.png)?

I am 99% sure if you drop an index.html into the top-level on that branch you will have a website.