Hi @JimMadge! Back here to expand here on the discussion with @da5nsy and @KirstieJane!

For #3213 - we documented this need to shift to a Github organisation according to the needs of working groups, in this table format here:

In the context of this shift to RTD, I am drawing from an emerging 'platform audit form', which has been previously been used to evaluate Newsletter platforms and Event organising platforms. This template could be used more broadly if research is needed to switch platforms:

I suggest the following format since we have decided to move to RTD – though please feel free to remix & shift around if it does not meet your needs.

@the-turing-way/infrastructure-working-group - I think this could be something we build together for a more standardised 'platform/infrastructure evaluation' system more broadly for the community. What do you think?

Thanks @aleesteele 🙏 🚀.

I feel I should say, I don't think we have decided on moving to RTD. In particular, I think we want to look at if support for translations is improved/worsened on RTD compared to Netlify. Although, I do think RTD is a sensible choice, the most natural, and the easiest.

I will add those tables (probably with some adjustments) to the top level comment.

I like that the tables summarise the considerations and decision process in an open way. That feels very important to get right. A while ago we did talk a lot about how one of the key roles of an infrastructure WG/maintainer would be to recommend when to change infrastructure.

I would worry that to strict a system might add unnecessary bureaucracy. Would putting the table templates in the community handbook and encouraging their use in an open place is a good balance?

A few notes about RTD deployment,

• Must call Sphinx, which means you run a pre-build command to write a Sphinx conf.py to file
• RTD has it's own stack.
  This is more up to date than Netlify, but presents potentially the same problems where we aren't in total control of the build
• RTD brings it's own dependencies and plugins

I've added notes about GH-pages to the opening comment. My strong preference would be to move to that rather than buy into yet another third party service that brings their own plugins and alike like RTD.

In all my other jupyterbook-based projects a tox.ini file is being used to control the build and it works beautifully the same way whether someone builds/tests locally, in a PR or in the deployment. While, in practice, reproducing issues someone run into on RTD can be rather painful and cryptic.

My only comment against GitHub Pages is that it doesn't provide deploy previews like Netlify and RTD do, and a lot of this community depend on that specific feature for review.

We do that preview through circleCI using the very same config files. In practice, this setup is way less painful than dealing with the mysteries of RTD failures.

(that kind of goes against my argument of adding another 3rd party dependency, but even with that bit of complexity we address most of the issues Jim mentions above vs RTD)

Great point about previews. I think whatever we do, we need some way to provide people with previews and to automate a comment linking to the preview in PRs.

In the same way as we can see CI as removing the burden on contributors to run tests/linting previews remove the need to build the book locally to see what it will look like.

Having a preview is certainly a must, no question about that. But I would also want to keep it easy to build stuff locally, and have it the same as what happens in CI (super useful to hunt down various issues). And this is exactly the case where RTD is lacking with its custom but not exactly well documented dependency.

As well as deploy previews, we will also need the ability to host the different language versions at either fr.book.the-turing-way.org or book.the-turing-way.org/fr (or something else, I have no strong opinion), as an example. Is this a possibility too in the implementation you're suggesting? Would we have to build our own "language selector" or wait until one is available upstream in Jupyter Book?

I totally get and agree with everything that @bsipocz is saying, but I'm also worried that atm you're the bottleneck to implementing this. So I think we need a plan to upskill the rest of the WG so we can spread the load of implementation and maintenance of it. And I think that's why we've leaned towards RTD in discussions so far, because at least both Jim and I have experience, even if it's a troublesome tech stack.

I totally get and agree with everything that @bsipocz is saying

Agreed. I think I'm trying to be pragmatic. The abstraction of RTD and difficultly making local/CI/RTD builds identical bothers me. I think the stuff we get for free with RTD (previous versions, deploy previews, language support) is swaying me to that side though.

I'm not sure if we have had (or need) some time to go over all the options together though. To make sure we all consider the options properly and know why we make the final decision we come to.

@JimMadge definitely feels like something for the next meeting's agenda