C dependencies on ReadTheDocs

Posted on

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):
    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 called 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.yml file at the root of my tree and I edited it with the following information.
  version: 3

  - 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.