📖 Add ReadTheDocs automation

[LecrisUT]

I will create a mystmd-temp slug to test if it all works as expected

Closes #968

[LecrisUT]

Any ideas on what is going on here? Why is packages/myst-parser/docs being built, and why does it not seem to be doing that when I run manually?

Edit: It seems RTD runs all command lines from the same working directory 😮‍💨. Have to chain a cd docs && to work around that

[LecrisUT]

Ready for review. Everything seems to be working: https://beta.readthedocs.org/projects/mystmd-temp/builds/?version=1

There is one issue though, the paths and url are not relocatable, i.e. the index root is set to https://mystmd-temp--1.org.readthedocs.build/en/1/ (/{lang}/{version}), but the generated documents are searching for /_assets, etc. (the files are accessible under /{lang}/{version}/_assets). It would be nice if this pathing can be fixed, since it seems that we have version control by default thanks to RTD's flyout.

For the sake of this PR, we can serve a single-version page.

Navigation also seems slightly broken in that https://mystmd-temp--1.org.readthedocs.build/quickstart does not translate to https://mystmd-temp--1.org.readthedocs.build/quickstart.html. Adding symlinks did not seem to work

[choldgraf]

This looks great to me - I believe that in RTD you can remove the en/latest prefix by checking this option (on the old RTD interface, it looks like you're using a new one):

[LecrisUT]

This looks great to me - I believe that in RTD you can remove the en/latest prefix by checking this option (on the old RTD interface, it looks like you're using a new one):

Indeed I have tried that, it did solve the /{lang}/{version}/ pathing, but the page redirection issue was still persistent. Maybe it's an issue on RTD for that that one.

But I figured that setting BASE_URL=${READTHEDOCS_CANONICAL_URL} is also compatible here, and it keeps the multi-version support that we get automatically from RTD 😉

[LecrisUT]

Btw, also worth investigating the console errors reported. I am not sure if it relates to the path sanitization, but they all seem to point to the build/_shared script paths. A bit hard to navigate though because there is no source-map to the .ts fiels.

[choldgraf]

I suggest that we merge this one in as-is, and then continue iteration on RTD preview builds via a RTD project that's linked to this repository. Then we can consider this "done" when we get a PR preview of our documentation.

@rowanc1 does that make sense to you?

[LecrisUT]

In that case when creating the RTD settings, the main website builder should be disabled so that myst.readthedocs.io is not yet created and/or the SEO does not prefer to the broken page yet.

[rowanc1]

@choldgraf and I are going to do some testing now in the mystmd RTD project.

[LecrisUT]

Was planning on quickly dropping the BASE_URL part here, but anyway, there are other issues to resolve with this, so can do that at that time. Also drop the bottom comment as unplanned upstream anyway

[rowanc1]

The preview is up here:
https://mystmd.readthedocs.io/en/latest/

The biggest issue (beyond hydration) is around the .html requirement.

[LecrisUT]

Yeah, both issues are on myst-to-react afaiu. At least the .html should be straighforward to pin down and it would make the RTD generated sites usable. RTD could also potentially fix it with: readthedocs/readthedocs.org#11220, but in the current configuration it is not possible.