Missing information in CONTRIBUTING.rst

[sgpearse]

This has been reported before in #48, but I'm still struggling to get a local instance of a readthedocs server running in docker. Like other users have done in the past, I need a local instance to debug a broken build.

docker run --rm -t -i readthedocs/build:latest /bin/bash

followed by

cd ~docs
git clone https://github.com/readthedocs/template
cd template
make html

Results in the missing dependencies (sphinx, sphinx-build) problem reported in #48. @humitos reports that the following will install these missing dependencies, however these commands are outdated. For example, there is no python binary in readthedocs/build:latest. I've tried using python3 and venv in lieu of virtualenv, but that requires an apt install python3.12-venv which has permission issues.

python -m virtualenv --no-download --no-site-packages myenv
source ./myenv/bin/activate
pip install --use-wheel --upgrade Pygments==2.2.0 setuptools<40 docutils==0.13.1 mock==1.0.1 pillow==2.6.1 alabaster>=0.7<0.8!=0.7.5 commonmark==0.5.4 recommonmark==0.4.0 mkdocs==0.15.0
sphinx<2 sphinx-rtd-theme<0.3 readthedocs-sphinx-ext<0.6

Is there an updated procedure on how one can get a local docker container running the RTD build system so I can debug why my build is failing?

[humitos]

We should probably delete the CONTRIBUTING file. We have this note in the readme:

These images are only for internal usage on Read the Docs project. They are not meant to build your documentation locally, to replace Read the Docs' service or to emulate it locally.

[humitos]

Is there an updated procedure on how one can get a local docker container running the RTD build system so I can debug why my build is failing?

It's not easy, no. You can try spinning up the development environment following https://docs.readthedocs.io/en/latest/development/install.html; which is not trivial. It's not worth the effort just to debug a build.

You should be able to debug your build on Read the Docs itself by running custom commands. See https://docs.readthedocs.io/en/latest/build-customization.html