Build fails when trying to build Python extension module

[cmacmackin]

Details

• Read the Docs project URL: https://peakingduck.readthedocs.io/en/develop/
• Build URL (if applicable): https://readthedocs.org/projects/peakingduck/builds/10544474/, https://readthedocs.org/projects/peakingduck/builds/10543237/
• Read the Docs username (if applicable): cmacmackin

Note: all of this is being done on the development branch; the master branch does not yet have any sphinx documentation.

Expected Result

I am trying to use Sphinx's autodoc features on a project with a compiled Python extension, in order to extract the docstrings contained within the compiled module. To do this, I added the following to my conf.py file:

import subprocess
from sysconfig import get_path
read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
if read_the_docs_build:
    complete = subprocess.run(['g++', '-DPEAKINGDUCK_EXPORTS',
                               '-I../thirdparty/pybind11/include',
                               '-I' + get_path('include'),
                               '-I../thirdparty/units/include',
                               '-I../thirdparty/eigen', '-I../include',
                               '-fPIC', '-fvisibility=hidden', '-shared',
                               '-o', '../PEAKINGDUCK.so',
                               '../py/peakingduck.cpp'])

The idea is to build the shared object library before running Sphinx so that autodoc can import it and produce documentation for the methods it provides. This works fine on my local computer, including when setting the READTHEDOCS environment variable to True.

Actual Result

When I tried submitting this to Read the Docs, one of two things happens:

• it hangs on running Sphinx, before exiting due to running out of build-time (https://readthedocs.org/projects/peakingduck/builds/10544474/)
• the compiler fails with the message

  g++: internal compiler error: Killed (program cc1plus)
  Please submit a full bug report,
  with preprocessed source if appropriate.
  See <file:///usr/share/doc/gcc-7/README.Bugs> for instructions.
  

  but sphinx is able to continue and just doesn't produce documentation with autodoc https://readthedocs.org/projects/peakingduck/builds/10542867/)

This appears to be the same bug as in #3185, so perhaps building in Conda will help as it did with that issue.

[cmacmackin]

I have tried switching over to Conda, as this appeared to work in #3185, but this caused the builder to run out of memory: https://readthedocs.org/projects/peakingduck/builds/10549300/

[cmacmackin]

After some investigation I discovered that the compiler was using too much RAM. I was able to reduce the amount it used sufficiently by playing with configurations of its internal garbage collector. This was achieved with the flags --param ggc-min-expand=10 --param ggc-min-heapsize=16384.

[humitos]

Thanks for sharing the workaround!