Compiling documentation in readthedocs


#1

Hi! I was following your tutorial on documentation, and everything is smooth until I compile it in readthedocs. I do not get a compilation error, I just get no text where the automodule and autofunction codes are. So, I followed the suggestion from the readthedocs FAQ about C based python libraries such as numpy, basically to use mock in conf.py. I did that with numpy and scipy, and now I get an error in the local compilation.

TypeError: attribute name must be string, not 'MagicMock'

Should I ignore it and push the changes anyway? In that case it would be weird that the same thing does not compile always

thanks
chuse


#2

Could you point to your repo?
This is the code I have used without issues:

import mock, sys
MOCK_MODULES = ['lantz', 'PyDAQmx', 'PyQt4']
for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = mock.Mock()

#3

https://github.com/josemiotto/pylevy

the code I used is the same as suggested in the FAQ. If I use exactly the one you just posted, I get (locally),

WARNING: autodoc: failed to import module 'pylevy.levy'; the following exception was raised:
cannot import name '__version__'

#4

I don’t know if it is relevant, I think it is not, but the requirements.txt created by freeze contains all the packages necessary to compile the docs, in addition to the ones to run the package. I deleted the former just in case there were more C-based packages there.


#5

I don’t see why it would give errors with numpy or scipy. I’ve just built the docs, without any errors:

https://pylevyaquitest.readthedocs.io/en/latest/

You can tweak the options if you go to the Admin tab when you are configuring the docs. If there are packages you don’t want to get auto-installed, you could generate a new requirements file, just for the docs. You can select to install your packages inside a virtual environment, and also specify which version of Python to use.


#6

no, take a look to the levy page, the text that should be there is not

https://pylevyaquitest.readthedocs.io/en/latest/levy.html


#7

I found the log of the sphinx compilation, this is it

Running Sphinx v1.7.7
    loading translations [en]... done
    making output directory...
    loading intersphinx inventory from https://docs.python.org/objects.inv...
    intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
    loading intersphinx inventory from http://docs.scipy.org/doc/numpy/objects.inv...
    intersphinx inventory has moved: http://docs.scipy.org/doc/numpy/objects.inv -> https://docs.scipy.org/doc/numpy/objects.inv
    building [mo]: targets for 0 po files that are out of date
    building [readthedocs]: targets for 2 source files that are out of date
    updating environment: 2 added, 0 changed, 0 removed
    reading sources... [ 50%] index
    reading sources... [100%] levy

WARNING: autodoc: failed to import module 'pylevy.levy'; the following exception was raised:
No module named 'pylevy'
WARNING: autodoc: failed to import function 'change_par' from module 'pylevy.levy'; the following exception was raised:
No module named 'pylevy'
WARNING: autodoc: failed to import function 'random' from module 'pylevy.levy'; the following exception was raised:
No module named 'pylevy'
WARNING: autodoc: failed to import function 'levy' from module 'pylevy.levy'; the following exception was raised:
No module named 'pylevy'
WARNING: autodoc: failed to import function 'fit_levy' from module 'pylevy.levy'; the following exception was raised:
No module named 'pylevy'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 50%] index
writing output... [100%] levy

generating indices... genindex
writing additional pages... search
copying static files... WARNING: html_static_path entry '/home/docs/checkouts/readthedocs.org/user_builds/pylevy/checkouts/latest/docs/source/_static' does not exist
WARNING: html_static_path entry '/home/docs/checkouts/readthedocs.org/readthedocs/templates/sphinx/_static' does not exist
done
copying readthedocs static files... done
copying searchtools... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 7 warnings.

The HTML pages are in _build/html.

So basically it does not find the package, but only sends a warning, not an error. I am not sure of how to solve this.


#8

I have checked, when you install your package, it is called levy, not pylevy.
You can see the docs here:
https://pylevyaquitest.readthedocs.io/en/latest/levy.html

And the docs source code here:

Also, I have removed the mock from the config.py. Since you are actually using numpy in the init, it will fail when you mock it. You can mock imports, but not the execution to my understanding.


#9

Ha! that makes a lot of sense, it uses the module name, not the package.

this is great, thanks a lot!


#10

If you install your package in a clean virtual env, it will get named as levy. I guess is a thing with the setup.py file and the naming of the folders.
Also, since you have this line in your conf.py:

sys.path.insert(0, os.path.abspath('../../../'))

It works locally, because you are appending the parent folder of the PyLevy folder. If you would rename your project folder (which is arbitrary in these matters), and that would be the case when you download the repo as a .zip, the local compilation of the docs would fail.