add Readthedocs config yaml file

[valeriupredoi]

For RTD setup, if we decide to set up RTD for cfs3.

[bnlawrence]

As discussed, might hold on this until we can get some input from @sadielbartholomew and @davidhassell on a decisions: "real" readthedocs or github pages?

[sadielbartholomew]

For what it's worth, I don't generally see the need for Read The Docs over GitHub Pages unless for much more popular libraries e.g. something like Dask or numpy etc where analytics are useful, though RTD do provide a list of their apparent advantages here : https://about.readthedocs.com/comparisons/github-pages/. Note however the major bias of RTD having written said list and certain points are dubious e.g. 'multiple versions' of docs being serv-able is noted as being not possible with GP whereas it is for sure - probably not as easy to set up but totally do-able as proved by the cf-python and cfdm docs. Other things they state aren't possible in GP are, in my experience, perfectly possible - albeit you have to do more yourself to set it up.

I prefer GitHub Pages personally because, despite a bit more setup overhead;

• you get more control, including for styling and theming (RTD used to enforce one theme and it was one I hated);
• it is more environmentally sustainable I believe, because RTD does regular builds whereas with GP you can only build when you need;
• builds can be noticeably laggy at times depending on the queues of other RTD builds.

[davidhassell]

I'm with Sadie. I really don't like RTD (bad colours, bad page width, advertisements, etc.), and my heart sinks a little when I have to read it.

That said, it's your library, Bryan, and you won't hear any complaints from me if you want to use it - whatever works you :-)

[sadielbartholomew]

Advertisements! Yes good point David - nobody wants those. You can pay to remove them 'opt-out' but I doubt we'd want to do that. So weigh that up with the other major pros and cons.

That said, it's your library, Bryan, and you won't hear any complaints from me if you want to use it - whatever works you :-)

Same here (though I might forgive myself one moan about the ugly theming and distracting ads if you do go with RTD).