Multi-project yaml syntax

[LecrisUT]

What's the problem this feature will solve?

I was looking at sphinx-themes.org and was considering if the build system can be simplified and automated with RTD. If the sub-projects can be managed by the yaml, I think that is indeed doable.

This could help in other project situations where the documentation is sphinx based, but there are other systems for the main website or components, e.g. a static html page or a myst article.

Describe the solution you'd like

Expand the yaml syntax to allow for a project dictionary, where all of the inner components have the same json schema (minus version, etc.) as the current schema.

version: 2
project:
  /:
    sphinx:
      configuration: docs/conf.py
  /themeA:
    sphinx:
      configuration: docs/themeA/conf.py

If the yaml file contains project, than the UI interface should be grayed out unless requested to override, at which point only the project./ or top-level schema is read

Adding/Deleting subprojects would be tricky in such cases though, but any automation that the user would create would probably be worse.

Alternative solutions

Expose the specific sub-project build through a GH action interface. Relevant issue

[humitos]

I was looking at sphinx-themes.org and was considering if the build system can be simplified and automated with RTD. If the sub-projects can be managed by the yaml, I think that is indeed doable.

Some time ago, I tried to build this project on Read the Docs to try out its complexity 😄 . I was able to and it's done at https://beta.readthedocs.org/projects/sphinx-themes/ and hosted at https://sphinx-themes.readthedocs.io/en/latest/. I did not need anything special other than build.jobs and run some specific commands.

Expand the yaml syntax to allow for a project dictionary, where all of the inner components have the same json schema (minus version, etc.) as the current schema.

This solution sounds pretty complex to me and requires rewriting the whole config file together with rewriting a lot of Read the Docs internals that's based on "one project per sub-project" and the relations between them. I'm not visualizing this as doable at this point, honestly 😄

I will leave this issue open in case you (or anyone else) want to provide more feedback here. Otherwise, I will close it as not planned in the next following weeks.

[LecrisUT]

Some time ago, I tried to build this project on Read the Docs to try out its complexity 😄 . I was able to and it's done at https://beta.readthedocs.org/projects/sphinx-themes/ and hosted at https://sphinx-themes.readthedocs.io/en/latest/. I did not need anything special other than build.jobs and run some specific commands.

Oh, awesome, mind if I advertise it there?

This solution sounds pretty complex to me and requires rewriting the whole config file together with rewriting a lot of Read the Docs internals that's based on "one project per sub-project" and the relations between them. I'm not visualizing this as doable at this point, honestly 😄

Agreed it is quite complex, but I think it could be useful, e.g. a project might want to version-wheel only the relevant API documentation (served as a subproject with /docs/${version}/ root), while the main project is a static welcome page (served as /). This is not possible with just build.jobs since these 2 would have different project settings, but they have the same git repo.

For now the first support could exclude any sub-project management, and simply consider supporting reading a sub-project from the yaml:

• All sub-projects are per-defined
• Inside the project setting, have a project field to identify which part of the yaml file to read
• In the build configuration, read the whole yaml as is, and if the project setting is set, dict.update (recursively) the fields that are defined in the project dictionary

requires rewriting the whole config file

The idea is not to bump version to 3 and be backwards incompatible, but to add the project dictionary. All configurations defined in top-level would still propagate down, but anything define there would overwrite/append to the configuration as if it was written on the top-level

---

There also is another intermediate solution, where you have multiple readthedocs.yaml files scattered around. That may work, but I am not sure how that will interact with the GH actions, if they can be deployed side-by-side, e.g. in a PR, how would the linking from one project to its subproject work?

[humitos]

Note that we have already talked about project setting defined in the YAML file and it's a pretty hard problem to solve and that's why we haven't build it. See the discussion in #9188

Agreed it is quite complex, but I think it could be useful, e.g. a project might want to version-wheel only the relevant API documentation (served as a subproject with /docs/${version}/ root), while the main project is a static welcome page (served as /). This is not possible with just build.jobs since these 2 would have different project settings, but they have the same git repo.

This is currently possible using subprojects and a custom YAML path.

There also is another intermediate solution, where you have multiple readthedocs.yaml files scattered around. That may work, but I am not sure how that will interact with the GH actions

What kind of interaction are you talking about here between Read the Docs and GH actions?

[LecrisUT]

Note that we have already talked about project setting defined in the YAML file

For the first implementation, I am not considering having project settings inside yaml. The first implementation would still have all project settings in the web UI, but allow for (sub-)project override of the options that are already defined. in the schema.

Indeed multiple custom yaml paths would be equivalent but a bit cumbersome to manage.

What kind of interaction are you talking about here between Read the Docs and GH actions?

• Setting webhooks for 2 projects on the same git repo, let's say project A and subproject A.B. Using the UI and RTD app I don't think it's possible, but setting up the projects manually might be possible
• PR builds. Let's say both A and A.B enable the PR support, how does the slug url get served A--1.readthedocs.io, A-B--1.readthedocs.io? Would we be able to test the link navigation of A links to A.B files, the worst situation being sphinx-inv links?