📖 Enable RTD again

[LecrisUT]

Let's keep this in draft so we can explore how to fix the RTD issues. Quick comment @rowanc1 can you keep the RTD project alive so that it can run on PRs. It is fine if it fails on main/other PRs due to a lack of .readthedocs.yaml file, it's just that it would be good to have it here so that we can explore all of the issues and potential solutions across the myst-theme repo (i.e. open a similar branch there and point packages.json to the repo branch where we can explore potential fixes)

TODO:

• Write todo
• The landing page of the preview is broken, due to some kind of javascript error
  @choldgraf Can you comment with a screenshot of this?
• Bare links need to redirect to .html files: myst-to-react issue
  • Temporary solution would be to have the hosting provider do the redirect, but that is not ideal because local navigation of the static site through index.html is still broken
• Overwrite robots.txt
  • Maybe this is to be done on the RTD settings?
• Handle hydration issues: myst-to-react issue
• Add flyout menu support

Closes #1133

[LecrisUT]

Suggested change

	- cd docs && myst build --html
	- cd docs && myst build --html --execute

Last time it was suggested to use --execute, but my understanding is that only affects the running of notebooks. For these issues it should not be relevant right? Is it also used in the mystmd pages?

[rowanc1]

Thanks @LecrisUT for reopening this. @choldgraf I think you turned off the preview on RTD, are you in a place to re-enable?

[choldgraf]

I can do that but just want to make sure that we are ready to do it. If I enable it then GitHub will mark every PR as failing until the rtd job is re enabled. Do we want that now or do we want to wait until we are actively fixing this before doing so?

[LecrisUT]

Oh fair point. I can make a small page to redirect here that would be run on main and all other branches

[humitos]

You can activate this branch in RTD without enabling the pull request build if you want. That way, this branch will be built on every commit on RTD... Getting an outcome similar to the PR builds.

[humitos]

Overwrite robots.txt

You can do this by generating this file as you want and saving it at the root of the HTML output directory. More at https://docs.readthedocs.io/en/stable/reference/robots.html

[LecrisUT]

It would not have the nice PR link to show it, and it would have to be on a new branch on the main repo, but that would work