Nothing really fancy here but I came across a difficulty when I tried to use the ReadTheDocs service. I got errors during the compilation process on their server because my project requires the Portaudio library in order to work. Of course, ReadTheDocs don’t let people install anything silly on their servers (and they are right) and there is a work around for those who are interested in using their amazing service.
It seems that several people comes across this issue regularly (or here as well). Unfortunately, the official documentation isn’t very clear about how to handle it. After several trials and research on the web, I found a workaround. If we follow the path of the official documentation, it is advised to mock your C libraries by adding few lines of code in your conf.py
!!! I’m not really sure if that part is useful regarding the follow up I did. As I use the YAML file to tell the virtual environment, what is required, mocking the C library doesn’t really make sense in this context.
import sys from unittest.mock import MagicMock class Mock(MagicMock): @classmethod def __getattr__(cls, name): return MagicMock() MOCK_MODULES = ['pygtk', 'gtk', 'gobject', 'argparse', 'numpy', 'pandas'] sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
What isn’t said (maybe the documentation could be improved on this side), is
that you can modify the RTD environment by created at the root a YAML file
readthedocs.yml as given in the documentation as well. This allows
you to alter the documentation compilation process. Moreover, in the
documentation given by the library Astropy, you have an idea of what to
do. On my side here the steps I did:
- I activated in the administration of my readthedocs project the
Install your project inside a virtualenv using setup.py install
- Still in the administration I activated the option
Give the virtual environment access to the global site-packages dir
- I created a
readthedocs.ymlfile at the root of my tree and I edited it with the following information.
python: version: 3 formats: - none
Basically, I tell the system to only use Sphinx and another package (to
compile the Google docstring format) that were stored in my
requirements_docs.txt and to compile everything using python 3 (I’m pretty
sure it would work with python 2.7). I pushed that and… it worked.