4

I am trying to build my documentation on Read the Docs but I am getting a dreaded "Module not found" error. If I issue make docs locally in my project's root, everything builds fine so the "Module not found" error is very strange to me.

I am using the PyPackage Cookiecutter template. Here is my project's relavent portion of its tree:

.
├── docs
│   ├── authors.rst
│   ├── conf.py
│   ├── contributing.rst
│   ├── history.rst
│   ├── index.rst
│   ├── installation.rst
│   ├── make.bat
│   ├── modules.rst
│   ├── readme.rst
│   ├── scattergrid.rst
│   └── usage.rst
├── requirements_dev.txt
├── scattergrid
│   ├── __init__.py
│   ├── cli.py
│   └── scattergrid.py
├── setup.cfg
├── setup.py
├── tests
│   ├── __init__.py
│   └── test_scattergrid.py
└── tox.ini

Below is the successful local build in the same project issuing make docs in the root:

Running Sphinx v3.0.4
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 9 source files that are out of date
updating environment: [new config] 9 added, 0 changed, 0 removed
reading sources... [100%] usage
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] usage
generating indices...  genindex py-modindexdone
highlighting module code... [100%] scattergrid.scattergrid
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.
python -c "$BROWSER_PYSCRIPT" docs/_build/html/index.html

Below is the error from Read the Docs:

Running Sphinx v1.8.5

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/checkouts/latest/docs/conf.py", line 20, in <module>
    import scattergrid
ModuleNotFoundError: No module named 'scattergrid'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/cmd/build.py", line 300, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/application.py", line 201, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/config.py", line 203, in read
    namespace = eval_config_file(filename, tags)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/config.py", line 380, in eval_config_file
    raise ConfigError(msg % traceback.format_exc())
sphinx.errors.ConfigError: There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/checkouts/latest/docs/conf.py", line 20, in <module>
    import scattergrid
ModuleNotFoundError: No module named 'scattergrid'


Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/envs/latest/lib/python3.8/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/scattergrid/checkouts/latest/docs/conf.py", line 20, in <module>
    import scattergrid
ModuleNotFoundError: No module named 'scattergrid'

Here is the exact line where this error occurs in docs/conf.py.

import scattergrid
import os
import sys
sys.path.insert(0, os.path.abspath('..'))

This was setup by the cookiecutter template and you can see the absolute path is pointing one level up from the docs folder. Everything builds on Read the Docs if I don't include import scattergrid but of course then I don't have any real documentations so any help would be very appreciated!

Here is docs/scattergrid.rst built from the cookiecutter template:

scattergrid package
===================

Submodules
----------

scattergrid.cli module
----------------------

.. automodule:: scattergrid.cli
   :members:
   :undoc-members:
   :show-inheritance:

scattergrid.scattergrid module
------------------------------

.. automodule:: scattergrid.scattergrid
   :members:
   :undoc-members:
   :show-inheritance:


Module contents
---------------

.. automodule:: scattergrid
   :members:
   :undoc-members:
   :show-inheritance:
zstreet
  • 126
  • 9
  • 1
    If `scattergrid` is the module to be documented, you are not supposed to import it in conf.py. Sphinx will import the module if `sys.path.insert(0, os.path.abspath('..'))` is correct. – mzjn Jun 01 '20 at 07:07
  • The cookiecutter template makes the directory and module have the same name so it maybe confusing but everything is from the boilerpoint template and I just changes the actual contents of the `scattergrid.py` module but not it's name. Within `conf.py` it's path is pointing to the scattergrid directory and this allows the template to get `__version__` so the template isn't importing the module but the directory that contains the module (at least as I understand it). – zstreet Jun 01 '20 at 16:53
  • As I mentioned in my last sentence, not importing scattergrid in `docs/conf.py` does indeed build everything but the documentation doesn't show any module documentation from the module's comments. If I include it, it builds locally and the html generated has all the modules documentation but breaks on Read the Docs. – zstreet Jun 01 '20 at 17:12
  • When you build on Read the Docs, without `import scattergrid`, aren't there any errors or log messages? Is it possible that scattergrid has some requirements that are installed on your local machine, but are not stated in requirements.txt? – mzjn Jun 01 '20 at 17:45
  • 1
    I found you on GitHub. Here you import libraries that are not necessarily available on Read the Docs: https://github.com/zstreeter/scatterGrid/blob/master/scattergrid/scattergrid.py#L19. – mzjn Jun 01 '20 at 17:53
  • 1
    OHHHH I see! So it does find the module fine but Read the Docs cannot find the modules that are imported in the scattergrid module so it says it can't find the scattergrid module. That's a very confusing error message that lead me the wrong pathway. So can I add these requirements to my new `docs/requirements.txt` file and ReadTheDocs will be cool? Or what is the best practice for documentation on Read the Docs that requires other imports? – zstreet Jun 01 '20 at 17:59
  • I don't use RTD myself, but yes I think it will be cool if you add matplotlib, numpy etc to requirements.txt. I believe this is the best practice, see https://docs.readthedocs.io/en/latest/guides/specifying-dependencies.html. – mzjn Jun 01 '20 at 18:17
  • 1
    It built successfully, thank you! Though I don't see any of the documentation, I at least know what the issue was and I can work the rest out. The error had me looking in the wrong direction and I am not sure if I would have thought of the other imported modules without your assistance! – zstreet Jun 01 '20 at 18:36
  • 1
    @mzjn Could one of you post this solution as an answer and accept it? – AstroFloyd Jul 01 '21 at 12:20

0 Answers0