Readthedocs.org: Error: cannot connect to X server

[astrofrog]

First, thank you for enabling conda builds on RTD!

I am now trying to build the docs for http://www.glueviz.org using this, and am running into the following error:

Running Sphinx v1.3.1
making output directory...

Installed /home/docs/checkouts/readthedocs.org/user_builds/glueviz/checkouts/latest/doc/.eggs/astropy_helpers-1.1.1-py2.7.egg
/home/docs/checkouts/readthedocs.org/user_builds/glueviz/conda/latest/lib/python2.7/site-packages/matplotlib/font_manager.py:273: UserWarning: Matplotlib is building the font cache using fc-list. This may take a moment.
  warnings.warn('Matplotlib is building the font cache using fc-list. This may take a moment.')
: cannot connect to X server 

My readthedocs.yml file contains:

conda:
    file: .environment.yml

python:
    setup_py_install: true

and the .environment.yml contains:

name: glueviz

dependencies:
  - pyqt
  - numpy
  - matplotlib
  - pandas
  - astropy
  - dill
  - h5py
  - scipy
  - scikit-image
  - ipython
  - ipykernel
  - qtconsole
  - traitlets
  - pygments
  - pyzmq
  - mock
  - pytest

I think the cannot connect to X server error occurs when PyQt4 is imported.

On Travis, I normally fix this by doing:

export DISPLAY=:99.0
sh -e /etc/init.d/xvfb start

Is there any way of doing something similar on RTD?

[Cadair]

I would like to second @astrofrog on you supporting conda, it's really cool!

I am also having this problem with the X server, I am trying to import VTK thorugh Python and the conda packages have been built with an X server depenancy. So some way around this problem, other than custom building packages, would be great.

Thanks again!

[agjohnson]

Is there a better way to mock this? Running X server is not optimal.

[astrofrog]

@agjohnson - I'm not aware of any other solutions for now. We usually always run xvfb for these kinds of builds on Travis and it doesn't seem to cause any issues.

[astrofrog]

Having said that, I may have found a way to work around the issue in my specific case (but not 100% sure yet). I will report back!

[Cadair]

@agjohnson Due to the conda package for VTK being linked against libGL and not having OSMesa support compiled in, the only way to not have an X server is for me to recompile the package. Which I am trying to do, but without any success so far.

Thanks.

[Titan-C]

Is there any progress on this? I'm trying to build the documentation with some mayavi examples and I need the X server. In travis I just set up a headless server as pointed out in the first post. Is it possible to use it here too?

[Cadair]

No progress yet, as I said above I think the only practical way is to compile without X support. That is on my todo list but I have no idea if/when I will get to it.

[ederag]

Having xvfb-run on readthedocs would help a lot. A use case can be found in this question on stackoverflow.

[ederag]

Since https://github.com/sphinx-doc/sphinx/issues/4956 is solved, sphinx-1.7.5 would work around this issue for PyQt (with autodoc_mock_imports).

[stsewd]

Anyone can test if this solution https://github.com/rtfd/readthedocs.org/issues/1951#issuecomment-392955385 works as expected? If so, probably there is nothing else to do from the rtd side, right?

[ederag]

Yes, for this solution to work, rtd just has to upgrade the underlying sphinx to 1.7.5.
This is not the case yet.
Last build was " Running Sphinx v1.7.4"

[stsewd]

@ederag you can specify any version of sphinx in your requirements.txt file

[ederag]

Perfect. It does not bypass the setup.cfg.
For others, I just created a docs/requirements.txt with a single line

sphinx==1.7.5

and declared docs/requirements.txt in the readthedocs project
admin>advanced settings>Requirements file
Thank you, readthedocs is great !

[ederag]

It works fine, though some server load could be saved.
Currently PyQt5 is still installed
Installing PyQt5 in the python setup.py install --force build stage.
Ideally, mocked modules would not be installed.
Meanwhile, is it possible to set a negative requirement ?

[Titan-C]

In our use case it still doesn't work, we don't want to mock the imports that use the X server, we want to effectively use it. But our current work around of building the docs in travis and pushing to github pages works well enough.

[banesullivan]

FYI for others trying to figure out how to setup headless displays on Read The Docs:

I ran into this issue using sphinx-gallery with vtki to build these examples in our documentation.

Since RTD cannot handle headless displays, I outright switched my projects to deploying from Travis to GitHub pages using doctr: https://github.com/drdoctr/doctr

It works wonderfully and now we have a custom job that builds and deploys the docs on Travis which turns up as a status check on PRs - hope this helps others out there struggling to get RTD to meet their projects' needs!

Also, I created a ci helper script that can handle setting up all of this on Travis - simply add this to your .travis.yml:

dist: xenial # must use xenial for vtk/vtki

before_install:
  # configure a headless display for vtk/vtki
  - git clone --depth 1 git://github.com/vtkiorg/gl-ci-helpers.git
  - source ./gl-ci-helpers/travis/setup_headless_display.sh

then build your docs and use doctr to deploy!