The procedure described in CONTRIBUTING.rst is broken

[briskycat]

It says:

Once your image is built, you can test your image locally by running a shell in
a container using your new image::

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

This will put you into the root path in the container, as the docs user.
From here you can head to your home path (cd ~docs) and run normal
Python/Sphinx/etc operations to see if your changes have worked. For example::

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

When I try to follow this procedure I get this:

$ docker run --rm -t -i readthedocs/build:latest /bin/bash
docs@86df77b69feb:/$ cd ~docs
docs@86df77b69feb:~$ pwd
/home/docs
docs@86df77b69feb:~$ git clone https://github.com/readthedocs/template
Cloning into 'template'...
remote: Counting objects: 30, done.
remote: Total 30 (delta 0), reused 0 (delta 0), pack-reused 30
Unpacking objects: 100% (30/30), done.
Checking connectivity... done.
docs@86df77b69feb:~$ cd template/
docs@86df77b69feb:~/template$ make html
make: *** No rule to make target 'html'.  Stop.
docs@86df77b69feb:~/template$ ls
AUTHORS.rst  README.rst  docs
docs@86df77b69feb:~/template$ ls docs/
Makefile  authors.rst  conf.py  contributing.rst  history.rst  index.rst  installation.rst  make.bat  readme.rst  usage.rst
docs@86df77b69feb:~/template$ cd docs/
docs@86df77b69feb:~/template/docs$ make html
Makefile:12: *** The 'sphinx-build' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the 'sphinx-build' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/.  Stop.

The same happens when I try docker run --rm -t -i readthedocs/build:2.0 /bin/bash

[eine]

Seems that sphinx and the theme are not installed. This worked for me:

docker run --rm -tv /$(pwd):/src readthedocs/build:latest bash -c "\
pip3 install sphinx sphinx_rtd_theme && \
cd ~ && \
git clone https://github.com/readthedocs/template && \
cd template/docs && \
make html && \
mv _build /src/sphinx-build"

[humitos]

Hi! Thanks for the report.

Yeah, the image doesn't contain all the python packages needed to build the documentation since rtd.org creates a venv and install some packages by default on this env. So, to imitate the behaviour from rtd.org it's needed to do:

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

Would you like to propose a PR for the docs?

[eine]

I wouldn't mind to open a PR in order to enhance the docs. However, I am not sure about the content I should add. The solution I provided works for html output generation. So does yours (I expect). Therefore, what's the point in enhancing the test instructions if only one of the many options supported by RTD is tested there?

I mean, I am missing a command which replaces 'make html' with <run_full_rtd_buil>. Then, project 'template' should use most of the resources available inside the container. That would make test instructions be 'real' tests.

[humitos]

This image/repostiroy is not to build RTD documentation itself outside the RTD codebase. So, the idea of "Test locally" is useful when you want to modify the image (for example when a latex font is missing and you want to add it to the docker image). So, you build your custom image and test that your documentation build without problems. If it builds, you can propose a PR with the addition of that font. That's the idea of the "Test locally".

So, in case that the instructions for that are confusing, you can create a PR explaining those steps in a better way.

[eine]

So, the idea of "Test locally" is useful when you want to modify the image (for example when a latex font is missing and you want to add it to the docker image). So, you build your custom image and test that your documentation build without problems.

The point here is that AFAIK executing make html does not test the new latex font. You need to execute make latex. Therefore, to cover all possible modifications, it should be make all, as long as these two conditions are met:

• readthedocs/build:latest includes all the dependencies to execute every option in https://github.com/readthedocs/template/blob/master/docs/Makefile
• https://github.com/readthedocs/template/blob/master/docs/Makefile tests every dependency in https://github.com/rtfd/readthedocs-docker-images/blob/master/Dockerfile

The following snippet works for me:

docker run --rm -t readthedocs/build:latest bash -c "\
pip3 install sphinx sphinx_rtd_theme && \
cd ~ && \
git clone https://github.com/readthedocs/template && \
cd template/docs && \
make html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latexpdf text man texinfo info gettext changes xml pseudoxml linkcheck && \
ls -la _build"

But doctest or latexpdfja produce errors.

Do you know whether it is possile to execute make all instead of writting every option? Does the snippet above use every dependency available in the image?

---

BTW, I tried the solution above, but I get:

$ docker run --rm -t readthedocs/build:latest bash -c "\
> cd ~ && \
> 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 && \
> git clone https://github.com/readthedocs/template && \
> cd template/docs && \
> make all"
New python executable in /home/docs/myenv/bin/python
Installing setuptools, pip, wheel...done.
bash: 40: No such file or directory

[humitos]

The point here is that AFAIK executing make html does not test the new latex font. You need to execute make latex.

Yeah. I mentioned just an example of the flow to test it.

readthedocs/build:latest includes all the dependencies to execute every option in readthedocs/template:docs/Makefile@master

This repo seems to be completely unmaintained (last commit 2014), so I'd say that it was just a test or an idea that was never really used.

Do you know whether it is possile to execute make all instead of writting every option?

I don't know. Just to mention, RTD doesn't use make at all, it calls the sphinx-build command directly.

Does the snippet above use every dependency available in the image?

No. It's complicated to test all the dependencies together since there is no project template that uses all of them; but I think it'd be awesome to have something like that to ensure that any new change to the docker-images doesn't break anything.

[eine]

This repo seems to be completely unmaintained (last commit 2014), so I'd say that it was just a test or an idea that was never really used.

No. It's complicated to test all the dependencies together since there is no project template that uses all of them; but I think it'd be awesome to have something like that to ensure that any new change to the docker-images doesn't break anything.

Well, do you know a few projects which use non-frequent or even rare features?

I don't know. Just to mention, RTD doesn't use make at all, it calls the sphinx-build command directly.

If you inspect the Makefile, you'll find that every call is to sphinx-build. However, the builders which are actually used in RTD.org (e.g. https://readthedocs.org/projects/ghdl-devfork/builds/6440145/) are custom (named readthedocs and readthedocssinglehtmllocalmedia) and undocumented: http://www.sphinx-doc.org/es/stable/invocation.html#cmdoption-sphinx-build-b

[agjohnson]

We could perhaps also deviate from prescribing sphinx-build or make is run, and instead run a test suite? This might be the most useful for users testing changes to the images. I can open a ticket for this with some ideas.

Otherwise, testing a full pdf and epub build should probably be the point of the test build. I'd vote for the minimal number of steps/requirements to test a project build -- so no virtualenv and we don't suggest all of the RTD dependencies.

Edit: Opened #53 to discuss integration tests