sphinx autodoc for python doesn't show anything :(

[DominiqueMakowski]

Hey,

I have this python package that I'd like to automatically document using Sphinx. I've inserted docstrings in every functions and classes.

I made an account on ReadTheDocs, and did the setup accordingly (i.e., a docs/ dir with a conf.py file). Then, basically, I've tried almost everything: every combination of autodoc::, autofunction::, autoclass::; I tried using the same conf.py file as other packages which documented API (with specific changes made according to my case, of course); but it just doesn't work, the API page remains inexorably empty...

I just can't figure out what I'm doing wrong... 😢

Here's the link of the docs/ dir

Details

• Project URL: http://readthedocs.org/projects/neuropsydia/
• Build URL (if applicable):
• Read the Docs username (if applicable): DominiqueMakowski

Expected Result

Autodoc the module based on the docstrings inserted in every functions

Actual Result

The API page remains empty

[c-bata]

+1

I bumped into the same problem.

[thw17]

Has anyone managed to solve this?

I'm running into the same issue. Everything is building correctly except the API page, on which only the first function on the alphabetically first submodule is visible. Nothing in this thread has helped. I also tried moving all sphinx-apidoc output into an api directory (as some have suggested), this only adds the API structure (i.e., the submodule names, etc.), but still only the single function is visible.

In all cases, everything builds correctly locally (e.g., make html locally), and the API is complete. This seems to be specific to readthedocs.

[c-bata]

In my case, the cause of sphinx autodoc not working is ReadtheDocs doesn't support Python 3.5 (refs #1990). My project uses typing module added from python3.5, so raised ImportError in running sphinx-build:

• build: https://readthedocs.org/projects/kobin/builds/4799776/

[humitos]

@c-bata RTD supports Python 3.5 now, so you should be able to build your docs. Can you confirm that was your real issue?

[humitos]

@DominiqueMakowski I think your issue is not related with a bug on RTD but how you are mocking pygame. I tried to build your own repo in a local venv and I got this:

/home/humitos/readthedocs/repositories/Neuropsydia.py/docs/api.rst:6: WARNING: autodoc: failed to import module u'neuropsydia'; the following exception was raised:
Traceback (most recent call last):
  File "/home/humitos/.virtualenvs/tmp-8daeadb00049b321/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 385, in import_object
    __import__(self.modname)
  File "/home/humitos/readthedocs/repositories/Neuropsydia.py/neuropsydia/__init__.py", line 4, in <module>
    from .core import *
  File "/home/humitos/readthedocs/repositories/Neuropsydia.py/neuropsydia/core.py", line 2, in <module>
    from .screen import screen, screen_width, screen_height, monitor_diagonal
  File "/home/humitos/readthedocs/repositories/Neuropsydia.py/neuropsydia/screen.py", line 7, in <module>
    screen = pygame.display.set_mode((0,0), pygame.SRCALPHA | pygame.FULLSCREEN | pygame.DOUBLEBUF | pygame.HWSURFACE)
TypeError: unsupported operand type(s) for |: 'Mock' and 'Mock'
/home/humitos/readthedocs/repositories/Neuropsydia.py/docs/api.rst:9: WARNING: autodoc: failed to import module u'neuropsydia.screen'; the following exception was raised:
Traceback (most recent call last):
  File "/home/humitos/.virtualenvs/tmp-8daeadb00049b321/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 385, in import_object
    __import__(self.modname)
  File "/home/humitos/readthedocs/repositories/Neuropsydia.py/neuropsydia/__init__.py", line 4, in <module>
    from .core import *
  File "/home/humitos/readthedocs/repositories/Neuropsydia.py/neuropsydia/core.py", line 2, in <module>
    from .screen import screen, screen_width, screen_height, monitor_diagonal
  File "/home/humitos/readthedocs/repositories/Neuropsydia.py/neuropsydia/screen.py", line 7, in <module>
    screen = pygame.display.set_mode((0,0), pygame.SRCALPHA | pygame.FULLSCREEN | pygame.DOUBLEBUF | pygame.HWSURFACE)
TypeError: unsupported operand type(s) for |: 'Mock' and 'Mock'
/home/humitos/readthedocs/repositories/Neuropsydia.py/docs/api.rst:12: WARNING: autodoc: failed to import module u'screen'; the following exception was raised:
Traceback (most recent call last):
  File "/home/humitos/.virtualenvs/tmp-8daeadb00049b321/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 385, in import_object
    __import__(self.modname)
ImportError: No module named screen
/home/humitos/readthedocs/repositories/Neuropsydia.py/docs/api.rst:14: WARNING: autodoc: failed to import module u'ask'; the following exception was raised:
Traceback (most recent call last):
  File "/home/humitos/.virtualenvs/tmp-8daeadb00049b321/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 385, in import_object
    __import__(self.modname)
ImportError: No module named ask

So, I did a quick search on google and I found this other project https://github.com/ntasfi/PyGame-Learning-Environment that uses pygame and autodoc and I checked its docs/conf.py where it does some mock magic.

I think should research over there. pygame seems to be a non easy library to mock :)

On the other hand, it seems the autodoc sphinx plugin doesn't make the sphinx command to fail and that's why the Build is marked as Success but it's not true. cc @agjohnson is there something we can do on these cases to detect that exception and mark the build as failed?

[c-bata]

@humitos Thanks to support python3.5, my documentation was properly built by sphinx-autodoc :)
(this is my project: http://kobin.readthedocs.io/en/latest/api.html )

[DominiqueMakowski]

Well first thank you a LOT guys for your help and for digging into my project 😄

So based on @humitos advices I looked into the the other project I added some of their pygame-related lines into my conf.py (line 23, 24 and 27).

Now the build fails (which is a good thing I guess 😆 ). Looking at the log, it seems that the problem lies within a particular object (the pygame's surface (a screen window) created at the initialization of the module) that can't be mocked.

But still, I've no idea how to bypass this error, as the "screen" object is necessary for the other components to be initialized... 😞

Anyway thanks again!

Here's the compilation log's ending:

...
File "/home/docs/checkouts/readthedocs.org/user_builds/neuropsydia/checkouts/latest/neuropsydia/screen.py", line 7, in <module>
    screen = pygame.display.set_mode((0,0), pygame.SRCALPHA | pygame.FULLSCREEN | pygame.DOUBLEBUF | pygame.HWSURFACE)
TypeError: unsupported operand type(s) for |: 'Mock' and 'Mock'

Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/neuropsydia/checkouts/latest/neuropsydia/screen.py", line 7, in <module>
    screen = pygame.display.set_mode((0,0), pygame.SRCALPHA | pygame.FULLSCREEN | pygame.DOUBLEBUF | pygame.HWSURFACE)
TypeError: unsupported operand type(s) for |: 'Mock' and 'Mock'
The full traceback has been saved in /tmp/sphinx-err-3my7x3za.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

[humitos]

@DominiqueMakowski the problem is because the Mock class doesn't have the __or__ method and it's being used. So, another idea I have is to use the approach shown in the RTD FAQ regarding mocks and define the method __or__ in that MagicMock class.

Just a very simple example:

>>> class A(object):
...   def __or__(self, other):
...     return 3
... 
>>> A() | A()
3
>>> 

Let me know if you were be able to make it :)

[DominiqueMakowski]

@humitos I don't really understand, should I create a class in my conf.py, or in my module? Or define the or method within another existing class? thanks!

[humitos]

@DominiqueMakowski you have to create that class in your conf.py file, like here: http://docs.readthedocs.io/en/latest/faq.html#i-get-import-errors-on-libraries-that-depend-on-c-modules

But, in your case, I think you could workaround the | (because of pygame) by defining the __or__ in the class.

[davidshumway]

Seeing the same behavior. Only a single module is built. Working with the pygame module, as well.

http://stackoverflow.com/questions/42740771/sphinx-and-readthedocs-io-only-one-of-four-documentation-modules-show-up-remote

Just hacked up a solution... commenting out all instances of from pygame.locals import * and making sure not to run pygame's while-events loop. Then build the project and get it onto readthedocs. Finally, when it is all running properly, revert to the previous code (uncomment the from pygame.locals import * and make sure pygame's while-events loop is once again called).

This of course is not a solution for working with webhooks... 😢

==============

So another solution is to create a requirements.txt file to base of project with the contents:

pygame == 1.9.3

On readthedocs visit Admin>Advanced Settings and select Install your project inside a virtualenv using setup.py install. In the requirements field add the name of the requirements.txt file.

In conf.py add import pygame and from pygame.locals import *:

import os
import sys
import pygame
from pygame.locals import *
from mock import Mock
sys.modules['pygame'] = Mock()
sys.modules['pygame.constants'] = Mock()

Now it runs okay. There is no need to comment out from pygame.locals import * everywhere.

Caveat: Running pygame's while-event loop still does not work. That is okay if the program usually runs in if __name__ == "__main__":. That is, if it runs in if __name__ == "__main__": then when sphinx runs, sphinx will not run in this section. Of course, then there is the need to comment out testing code that is usually run using import Trumpocalypse.py.

if __name__ == "__main__":
    # Sphinx does not run this code.
    import sys
    surface = pygame.display.set_mode((854,480))
    surface.fill((255,120,71))
    GameState() # Starts pygame's while events loop.
else:
    # However, Sphinx does run this code!
    import sys
    surface = pygame.display.set_mode((854,480))
    surface.fill((255,120,71))
    # This is a test. But now it must be commented out,
    # or else Sphinx gets mad...
    GameState([ 0 ])

A solution for the test code is to add it into a function that may be called from the shell. Such as def run_tests():. Then to test the code run import Trumpocalyse.py and then Trumpocalypse.run_tests().

[DominiqueMakowski]

I've tried to follow your steps as best as I could. I created a requirements.txt file in which I put all the dependencies. Then, I ticked the "install inside a virtualenv" box in the readthedocs settings and provided the requirements.txt file. I added the following lines in the conf.py:

import pygame
from pygame.locals import *

sys.modules['pygame'] = mock.Mock()
sys.modules['pygame.constants'] = mock.Mock()

But it doesn't work 😢 I looked at the error and it seems related to a wrong numpy version...

[davidshumway]

Hi Dominique. Here is the built documentation: http://trumpocalypse.readthedocs.io/en/latest/. It mostly has the exact steps which were used.

Also, if it is of any use, here are the current software versions inside the virtualenv: pip_freeze.txt.

[humitos]

@DominiqueMakowski this is the error that I see in your build

numpy 1.12.1 is installed but numpy==1.11.2 is required by {'hrv'}

So, you have to pin numpy to that specific version since that's the one required for hvr. Another option, is to check if you can upgrade hvr to a more recent one.

Or... you can just remove the pinned versions for numpy and scipy.

[humitos]

@DominiqueMakowski I'm closing this one, please feel free to reopen if you consider necessary.