[Doc] Lists of implemented formats for both IOs and RawIOs not compiling

[jpgill86]

These section links point to the two lists of implemented formats in the version 0.9.0 docs:

• https://neo.readthedocs.io/en/0.9.0/io.html#module-neo.io
• https://neo.readthedocs.io/en/0.9.0/rawio.html#module-neo.rawio

These appear to be no longer compiling in the latest version of the docs:

• https://neo.readthedocs.io/en/latest/io.html#module-neo.io
• https://neo.readthedocs.io/en/latest/rawio.html#module-neo.rawio

There are just section headers with nothing in the sections.

[jpgill86]

I see this in the ReadTheDocs build log:

WARNING: autodoc: failed to import module 'core' from module 'neo'; the following exception was raised:
cannot import name 'NeuralynxRawIO' from 'neo.rawio.neuralynxrawio' (/home/docs/checkouts/readthedocs.org/user_builds/neo/envs/latest/lib/python3.7/site-packages/neo-0.9.0-py3.7.egg/neo/rawio/neuralynxrawio.py)
WARNING: autodoc: failed to import module 'io' from module 'neo'; the following exception was raised:
cannot import name 'NeuralynxRawIO' from 'neo.rawio.neuralynxrawio' (/home/docs/checkouts/readthedocs.org/user_builds/neo/envs/latest/lib/python3.7/site-packages/neo-0.9.0-py3.7.egg/neo/rawio/neuralynxrawio.py)
WARNING: autodoc: failed to import class 'rawio.ExampleRawIO' from module 'neo'; the following exception was raised:
cannot import name 'NeuralynxRawIO' from 'neo.rawio.neuralynxrawio' (/home/docs/checkouts/readthedocs.org/user_builds/neo/envs/latest/lib/python3.7/site-packages/neo-0.9.0-py3.7.egg/neo/rawio/neuralynxrawio.py)
WARNING: autodoc: failed to import class 'io.ExampleIO' from module 'neo'; the following exception was raised:
cannot import name 'NeuralynxRawIO' from 'neo.rawio.neuralynxrawio' (/home/docs/checkouts/readthedocs.org/user_builds/neo/envs/latest/lib/python3.7/site-packages/neo-0.9.0-py3.7.egg/neo/rawio/neuralynxrawio.py)
WARNING: autodoc: failed to import module 'rawio' from module 'neo'; the following exception was raised:
cannot import name 'NeuralynxRawIO' from 'neo.rawio.neuralynxrawio' (/home/docs/checkouts/readthedocs.org/user_builds/neo/envs/latest/lib/python3.7/site-packages/neo-0.9.0-py3.7.egg/neo/rawio/neuralynxrawio.py)

[jpgill86]

I see that in neo/rawio/, there is both a neuralynxrawio.py, which the build log seems to be trying to import from and failing, as well as a directory with the same name, containing another neuralynxrawio.py.

The first file, neo/rawio/neuralynxrawio.py, seems to contain an outdated copy of the contents of neo/rawio/__init__.py.

@PeterNSteinmetz, I see these changes were made in #905. What's going on here? Something seems not right.

[jpgill86]

Strangely, I'm not encountering problems building the docs locally, and the lists of implemented formats are building. Perhaps I have a different version of Sphinx installed, or some other package.

Regardless, it seems pretty clear from the ReadTheDocs build log that autodoc, which is responsible for assembling the lists, is being tripped up by the lack of a NeuralynxRawIO class in neo/rawio/neuralynxrawio.py.

[PeterNSteinmetz]

@jpgill86 I agree that the re-addition of that copy of neuralynxrawio.py above the directory is odd. If you want to do a pull request off of master which deletes that file, that would be good. I just tried setting that up and somehow when I try that, it creates a pull request with 102 commits, which is more complex than needed. Will likely take me a while to figure out what is going on with the branches in my repo to fix it.

[jpgill86]

Done: #933. We'll first need to see if that passes tests, and then it needs to be built on ReadTheDocs. Unless RTD is configured to build pull requests, which it probably isn't, #933 will need to be merged before we know if it helped with this issue.

[jpgill86]

#933 has been merged, but the lists of IOs and RawIOs are still failing to populate in the docs.

The ReadTheDocs log error has changed:

WARNING: autodoc: failed to import module 'core' from module 'neo'; the following exception was raised:
No module named 'neo.rawio.neuralynxrawio'
WARNING: autodoc: failed to import module 'io' from module 'neo'; the following exception was raised:
No module named 'neo.rawio.neuralynxrawio'
WARNING: autodoc: failed to import class 'rawio.ExampleRawIO' from module 'neo'; the following exception was raised:
No module named 'neo.rawio.neuralynxrawio'
WARNING: autodoc: failed to import class 'io.ExampleIO' from module 'neo'; the following exception was raised:
No module named 'neo.rawio.neuralynxrawio'
WARNING: autodoc: failed to import module 'rawio' from module 'neo'; the following exception was raised:
No module named 'neo.rawio.neuralynxrawio'

This new message is consistent with the facts that the previous log messages were suggesting autodoc was looking for the class NeuralynxRawIO in the empty module neo/rawio/neuralynxrawio.py, and now that file has been removed by #933. So, it's still looking for a (now non-existent) neuralynxrawio.py in neo/rawio, and it's ignoring the neuralynxrawio directory. I might have expected this if the __init__.py file was missing from the directory, but it isn't.

I still can't reproduce this when building the docs locally, and the neuralynxrawio module and NeuralynxRawIO class can both be imported on my machine. This is very puzzling...

[jpgill86]

I think I found the problem: #934

[jpgill86]

Indeed, merging #934 fixed the docs. We're all set!