2

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?

jez
  • 14,867
  • 5
  • 37
  • 64
  • Check the [build log](https://readthedocs.org/api/v2/build/9098417.txt) for these warnings `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(). looking for now-outdated files... none found`. Most likely, you do not tell RTD to install your package. See https://docs.readthedocs.io/en/stable/faq.html#my-project-isn-t-building-with-autodoc – Steve Piercy May 20 '19 at 23:31
  • @StevePiercy thanks, that put me on the right track (see answer) – jez May 21 '19 at 15:40

1 Answers1

0

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.

jez
  • 14,867
  • 5
  • 37
  • 64