readthedocs.yml

[Peter Bengtsson]

Humor me for being years behind the curve, but this was news to me.

tl;dr; You can write a readthedocs.yml that points to a specific file for
requirements.

My first attempt was to stuff Sphinx and sphinx_rtd_theme in the bottom of
my projects big requirements.txt
With hashes you have to also list Jinja2, MarkupSafe, Babel,
snowballstemmer, Pygments, imagesize and alabaster.
Still builds failed. It's because readthedocs, by default, builds with
Python 2.7 and that requires extra packages Python 3.5 didn't need.

Turns out, you can just put a readthedocs.yml file in your repo, and make
it point to a specific requirements.txt file. I first did this to override
the Python version but discovered the requirements_file directive.

Check out
https://github.com/mozilla/tecken/commit/2450608380b045b137c75ef1badeeabcfb8be1ff
and
https://github.com/mozilla/tecken/commit/e61618068fc1a9eebe7497c9cf0493ac0d9fccad

This might bite hard if you're trying to do more advanced integration with
your projects code via docs/conf.py with extensions or Django settings.

--
Peter Bengtsson
Mozilla Engineering Operations

[Erik Rose]

You can also set a requirements-file path through Admin → Advanced Settings on the RTD site itself.

[Peter Bengtsson]

Note, this separation broke `docker-compose run web ./bin/build_docs.sh`

So I'm adding this to my Dockerfile.dev

# Install Python dependencies specifically for building docs
COPY docs-requirements.txt /tmp/
# Switch to /tmp to install dependencies outside home dir
WORKDIR /tmp
RUN pip install --no-cache-dir -r docs-requirements.txt