Open LecrisUT opened 6 months ago
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 (minusversion
, 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.
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:
project
field to identify which part of the yaml
file to readproject
setting is set, dict.update
(recursively) the fields that are defined in the project
dictionaryrequires 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?
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 https://github.com/readthedocs/readthedocs.org/issues/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 justbuild.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?
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?
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 possibleA
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?
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 (minusversion
, etc.) as the current schema.If the yaml file contains
project
, than the UI interface should be grayed out unless requested tooverride
, at which point only theproject./
or top-level schema is readAdding/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