Improve troubleshooting guides

[astrojuanlu]

(Opening a blank issue because there's no option for "feature request" anymore)

More often than not when I'm troubleshooting Sphinx build problems, I still cannot reproduce exactly the result that appears on RTD. The most likely explanation is that there are slightly different dependencies versions, but it's hard to know for sure until one tries out.

Back in the day I used to have a very manual process of troubleshooting builds, which was launching a container, and copy-pasting the commands from the build logs. I've just tried to do that now again, but I got stuck pretty quickly, probably because I'm doing something different:

> docker run --platform linux/amd64 -it --name rtd-debug --rm readthedocs/build:ubuntu-22.04-2023.03.09 bash
$ apt-get update --assume-yes --quiet 
Reading package lists...
E: Could not open lock file /var/lib/apt/lists/lock - open (13: Permission denied)
E: Unable to lock directory /var/lib/apt/lists/
$ sudo apt-get update --assume-yes --quiet 
bash: sudo: command not found
$ su - root
Password:

There are some ways in which debugging Sphinx inside RTD could be nicer, for example:

• "Rebuild with SSH", like Circle CI does https://circleci.com/docs/ssh-access-jobs/
• Being able to download the whole working copy, not only see the HTML artifacts that get published only if the build succeeds (for example, to see files generated by sphinx.ext.autosummary)
• Having a pip freeze of the dependencies that got used in the end so that I can install exactly those locally
• ... ❓

These are all feature requests of various degrees of complexity. However, this issue is about improving the documentation. What I'd love to see is a page saying

• "We're sorry you're having a rough time with Sphinx" (joking - but yeah, I need a hug right now)
• "Here's how you can download exactly the same environment your project was built into" (hopefully doing a docker pull)
• "Here's how you can reproduce the steps" (even if it's copy-pasting, some copy-pasting that works)
• "Here's how you can run Sphinx in maximum debugging/verbosity mode" (with some tips about useful CLI flags or environment variables or configurations that I should touch)
• "Here's how you can attach a remote debugger to Sphinx running inside the container" (with links to the relevant documentation of, say, PyCharm and VS Code)
• ... ❓ possibly more

(Of course this has been a problem for me since forever, but only now I went ahead and opened an issue about it)

[humitos]

Honestly, I'm not sure how I can provide value to this issue. However, I've been seeing this issue open every time I check my notifications, so I'm going ahead an commenting something here 😄 .

I think the short answer for all of these proposal is "we don't want people to jump into this kind of darkness". In particular, using Read the Docs' Docker images, because they are not thought to be used outside Read the Docs. Even more, I've proposed to make that repository private multiple times and remove them from Docker Hub because it generates these confusions. That's why you are hitting the problems you are hitting: no sudo, hard to install (requires compiling) a Python version using asdf, etc.

We haven't exposed anything like what you are suggesting because it's hard to do it in a way that users and customers can feel comfortable using; and we can maintain 🥲

I think, for now, the best you can do to debug anything similar to that is using build.jobs to run any command you think it could help you to debug the problem. See https://docs.readthedocs.io/en/latest/build-customization.html

I'm sorry that I don't have a better answer 😞

[astrojuanlu]

In particular, using Read the Docs' Docker images, because they are not thought to be used outside Read the Docs.
I think, for now, the best you can do to debug anything similar to that is using build.jobs to run any command you think it could help you to debug the problem. See https://docs.readthedocs.io/en/latest/build-customization.html

It is the answer I was looking for, just needs a prominent place in the docs 😊 Thanks @humitos, as always!

[astrojuanlu]

On the topic of build.docs: how can one go from

"Read the Docs standard build process"

to

"Read the Docs standard build process, but replicated with build.commands"

so that, after that, users can gradually debug things? That transition path is what I'm missing to start using build.commands more. Otherwise, I will be stuck between "with build.commands it fails, on RTD it works" or the other way around.

[humitos]

"Read the Docs standard build process, but replicated with build.commands"

so that, after that, users can gradually debug things? That transition path is what I'm missing to start using build.commands more.

This is not yet possible. You can build with build.commands, but you are going to loose the nice Read the Docs integrations. In fact, this is exactly what I'm currently working on right now with the https://github.com/readthedocs/readthedocs-client/. It will allow users to integration with Read the Docs with "almost-zero conf". I've been doing a lot progress in the last weeks. However, it's not ready yet.

[astrojuanlu]

I understand that readthedocs-client provides the flyout and many other features. However, if I'm debugging, say, a Sphinx HTML output issue, I don't care about those integrations.

In other words: is it possible nowadays to recreate the same "backend" commands that RTD does, with build.commands?

[humitos]

I understand that readthedocs-client provides the flyout and many other features

Oh, I misunderstood your previous comment. I thought you wanted to migrate to build.commands because of this sentence: "That transition path is what I'm missing to start using build.commands more"

is it possible nowadays to recreate the same "backend" commands that RTD does, with build.commands?

Not at 100%, no. There is Python code from the application itself that cannot be run with build.commands.