Search code examples
python-sphinxread-the-docsautodoc

sphinx autodoc creates blank page on readthedocs, but correctly includes module docstring locally

I'm getting different results from autodoc when I run sphinx locally (versions 1.6.6 or 2.0.1 on Anaconda Python 3.6.8 for Mac) than when I run it on readthedocs.org (according to their log it's Sphinx version 1.8.5, and probably Python 2.7 since it's launched with python rather than python3).

The difference is in the results from the following file, Shady.Text.rst, which contains no more than:

Shady.Text Sub-module
=====================

.. automodule:: Shady.Text

Now, this sub-module happens to contain only a module-level docstring and no member docstrings—that's as intended, so the corresponding html page should contain the module docstring and no more. And this is exactly what happens when I run make html locally. However the result at https://shady.readthedocs.io/en/latest/source/Shady.Text.html is content-free (header only, no module docstring).

FWIW my autodoc-related entries in conf.py are:

autoclass_content = 'both'
autodoc_member_order = 'groupwise'

What am I doing wrong?

Solution

  • Thanks @StevePiercy for drawing my attention to the crucial lines in the raw log file:

    WARNING: autodoc: failed to import module u'Text' from module u'Shady'; the module executes module level statement and it might call sys.exit().
WARNING: autodoc: failed to import module u'Video' from module u'Shady'; the module executes module level statement and it might call sys.exit().

    (I had searched the 9000-line log file for .Text, because Text on its creates too many hits, but it hadn't occurred to me to search it for 'Text' in quotes).

    To me, the message is misleading: the problem is not that "the module executes module level statements" because that per se is allowed. I wasted some time after noting that some module-level statements seemed to be allowed in other sub-modules, and tried to bundle the offending module-level statements into a class decorator thinking maybe sphinx's mysterious module-level-statement-detector would miss them then...)

    No, the problem is that not the fact that the module-level statements exist and might call sys.exit(), but the fact that they did indirectly call sys.exit() during sphinx's compilation procedure. This was a quirk of the way I handle missing dependencies, which should probably be re-thought, but I could work around it for now by avoiding my sys.exit() call when os.environ.get('READTHEDOCS') is truthy.