[PROJ] Motion: Migrate proj.org to ReadTheDocs

[Howard Butler]

> On Feb 4, 2023, at 5:10 AM, Kristian Evers <kristianevers at gmail.com> wrote:
> 
> First of all, good job on this Howard and Mike. Thanks for taking the lead and following through with both the admin and grunt work!
> 
> I too am +0 for this but it can easily be turned into a +1:
> 
> RTD is great and the doc versioning is a killer feature. In light of Alan’s previous experiencing I’d like to have a basic contingency plan in case RTD turns out to not be great fit for the project in the long run. Returning back to GitHub Pages is the obvious solution to that problem. How big a pain is it to redirect proj.org away from RTD again if things turn south?
> 
> /Kristian
> 
>> On 3 Feb 2023, at 23.19, Alan Snow <alansnow21 at gmail.com> wrote:
>> 
>> +0
>> 
>> A few years ago, I had a less than great experience with RTD due to instability and lack of ability to be able to fix underlying issues with a highly constrained environment. I have found not using it to be a painless experience. However, it seems like they have been actively developing it and it does have some nice features. So, it is likely worth trying out.

Alan,

I think the situation has improved significantly as far as customization of the build environment on RTD in the past couple of years. PROJ has a complex documentation build setup – we build the library, run doxygen over it to generate breathe content, and we have a very large pdflatex output. All of these components are handled by current RTD, which supports running your own Python environments along with providing the ability to modify the ubuntu- and conda- based documentation building environment. It wasn't painless for us either, but after some iteration, Mike and I got it to a workable solution. You can follow our journey getting it going for PROJ in the ticket https://github.com/OSGeo/PROJ/pull/3538

> On Feb 4, 2023, at 5:10 AM, Kristian Evers <kristianevers at gmail.com> wrote:
> 

> How big a pain is it to redirect proj.org away from RTD again if things turn south?

Kristian,

We could go back to what we have now – a self-hosted GitHub Pages setup – by reenabling it and moving the DNS pointer. The downside of that it is more work to maintain going forward, updating it for anything but simple things must be done by people in the know, and multi-version docs would need to be hand-rolled. 

As far as I'm concerned, our proposed RTD implementation is better than our hand-crafted setup in all dimensions at this point. The biggest risk is the viability of RTD going forward, but that is a shared risk in the same way GitHub was before Microsoft bought it. Even so, if it went away, we could roll our own infrastructure as we have been doing.

Howard