How to specify "language" in .readthedocs.yaml?

[cissou8]

Details

• Read the Docs project URL: https://readthedocs.org/projects/siril-localized-doc/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/cissou8/

Why?

In preparation of the future depracation for projects without any yaml file, #10342, I've tried to figure out how to deal with this in the project holding our translations.
I had made a setup quite inline with the project listed in the documentation.

So basically, I have one conf.py file per language, and I've set one RTD project per language as well, all linked as translations of the english documentation (repo and RTD). Fine. Well not exactly because I see that it is not necessarily the correct conf.py which is automatically detected during builds, but provided the language it is overriden by the option passed to the sphinx-build command, the translations are built and deployed fine.

Now, my difficulty comes from setting a single .readthedocs.yaml. And here is my question:

How?

What would be the recommended way to deal with multiple languages repos?

I've been through the docs and I may have found ideas but I would like to know what is the official recommendation:

• I could create new yaml files (one per language, say .readthedocs_xx_XX.yaml and specify this filename in the Advanced Settings section of each translation.
  
  The fact that it is still experimental is the main reason why I'm asking.
• I could use a secret undocumented language tag in .readthedocs.yaml 😅? Smthg that would allow me to specify the path to the correct conf.py:

sphinx:
   configuration: docs/{language}/conf.py

• any other solution that I may have missed?

Cheers,

Cecile

[humitos]

could create new yaml files (one per language, say .readthedocs_xx_XX.yaml and specify this filename in the Advanced Settings section of each translation.
The fact that it is still experimental is the main reason why I'm asking.

This is probably the way to go. We added that "Warning: experimental feature" when we deployed it the first time because we weren't sure it was working for all the cases, but we haven't received any complain/issue/error from users yet. So, we should probably remove that message, or reduce it to "Beta:" maybe -- just in case 😄

However, note that you cannot use a name different than .readthedocs.yaml; so you will need different directories like docs/es/.readthedocs.yaml, docs/ja/.readthedocs.yaml, etc. (see #10468)

If it's not too much work on your side to try out this possibility, I'd go with it and see if it works fine.

I could use a secret undocumented language tag in .readthedocs.yaml sweat_smile? Smthg that would allow me to specify the path to the correct conf.py:

This is not supported currently and we don't plan to support it soon, at least. See #10462

[cissou8]

Thanks for the prompt reply, I'll test with one of the translations, and if all goes well, I'll port to the others. And I'll report back of course!

[cissou8]

OK, so for the time being, can't make it work... can't figure out relative to which path I should specify the requirements.txt file.

From the documentation, I gather it should be relative to root (where it is stored so requirements.txt). But the build fails:
https://readthedocs.org/projects/siril-localized-doc/builds/21383201/

If I assume it should be relative to the location of the yaml file (so ../../requirements.txt), it fails as well:
https://readthedocs.org/projects/siril-localized-doc/builds/21383081/

For info, the yaml is at docs/fr/.readthedocs.yaml (https://gitlab.com/free-astro/siril-localized-doc/-/blob/main/docs/fr/.readthedocs.yaml). I've setup for french langage only

Any suggestions?

[humitos]

From the documentation, I gather it should be relative to root (where it is stored so requirements.txt).

Root of the repository. So, it should be "docs/fr/requirements.txt"

Edit: sorry, I'm wrong. You have the requirements file at repository's root, so I'm not sure why it doesn't work. I'll double check tomorrow with the code

[cissou8]

Sure, thanks for investigating. For info, the last build that passed is this one: https://readthedocs.org/projects/siril-localized-doc/builds/21382752/
It fetches requirements.txt at the repo root alright.

[humitos]

I see. The documentation is fine and your YAML too. The problem is that the requirements.txt file you have in root of your project is a broken symlink: requirements.txt -> siril-doc/requirements.txt. The siril-doc/requirements.txt does not exist.

[humitos]

OK, I see. It's on a Git submodule. In that case, you have to use https://docs.readthedocs.io/en/stable/config-file/v2.html#submodules to tell Read the Docs to clone the submodules as well.

[cissou8]

Ooops, indeed. As the submodule was cloned automatically when there was no yaml file, I never figured out I had to do smtg about it. I'll give it a try and report back. Thanks again for the help!

[cissou8]

yeay! that was it... I've had my first sucessful build with the new set-up : https://readthedocs.org/projects/siril-localized-doc/builds/21387686/ 🥳
I'll deploy to the other translations and stable branch!
Many many thanks again!

Cheers,

C.