Split this documentation into a monorepo with multiple sites

[choldgraf]

Background and proposal

We currently use a single repository for documentation across multiple user personas. In these docs there are at least 3 personas represented:

1. users and community representatives of a hub who want to know best-practices in using the hub for research and education
2. administrators of a hub who want to learn how to solve problems, set up their hub, etc
3. interested parties who want to learn more about the kind of infrastructure and services we run

Having all of these docs in one place means that users need to do a bit more digging before they find the information they want. In addition, as our documentation grows more complex, we'll pay a bigger penalty for having all of it visible to all users on one site.

Instead, we could build multiple Sphinx websites, each geared towards a kind of user, cross-link them via the topbar in the 2i2c sphinx theme.

Implementation guide and constraints

To start with, an easy first step would be to structure our documentation with these user personas in mind. So for example:

docs.2i2c.org/users/foo
docs.2i2c.org/admins/foo
docs.2i2c.org/service/foo

For the monorepo approach, it should be possible to accomplish with Sphinx. I reached out to the ReadTheDocs folks and they mentioned that they do something like this as well:

https://github.com/readthedocs/readthedocs.org/blob/75b4a2ec9b417d71f0eacb3399722fdc465f111d/docs/conf.py#L4-L11

They also noted that they're working on an extension for RTD to make this easier:

readthedocs/readthedocs.org#8811

Updates and ongoing work

No response

[damianavila]

Should we wait for RTD to sort out the support for monorepo before pushing on this one? Or do we have other alternatives? Just wondering...

[choldgraf]

No strong opinions from me, I don't think it's a huge burning fire to make a multi-site layout anyway, so we can be patient I think