I'm trying to get started with Sphinx and seem to have relentless problems.
Command: docs/sphinx-quickstart
I answer all the questions and everything works fine.
Command: docs/ls
Everything looks normal. Result: build Makefile source
Command: sphinx-build -d build/doctrees source build/html
It seems to work. I was able to open the index.html file and see a "shell" of what I'm wanting.
When I try and put my actual source code as the source folder I run into problems.
Command: sphinx-build -d build/doctrees ../ys_utils build/html
Result:
Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
No builder selected, using default: html
loading intersphinx inventory from http://docs.python.org/objects.inv...
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
Traceback (most recent call last):
File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
__import__(self.modname)
ImportError: No module named ys_utils
Traceback (most recent call last):
File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
__import__(self.modname)
ImportError: No module named ys_utils.test_validate_ut
Traceback (most recent call last):
File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
__import__(self.modname)
ImportError: No module named ys_utils.git_utils
Traceback (most recent call last):
File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
__import__(self.modname)
ImportError: No module named setup.setup
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:4: WARNING: autodoc can't import/find module 'ys_utils', it reported error: "No module named ys_utils", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:10: WARNING: autodoc can't import/find module 'ys_utils.test_validate_ut', it reported error: "No module named ys_utils.test_validate_ut", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:12: WARNING: don't know which module to import for autodocumenting u'UnitTests' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:18: WARNING: autodoc can't import/find module 'ys_utils.git_utils', it reported error: "No module named ys_utils.git_utils", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:24: WARNING: autodoc can't import/find module 'setup.setup', it reported error: "No module named setup.setup", please check your spelling and sys.path
WARNING: master file /home/ricomoss/workspace/nextgen/ys_utils/index.rst not found
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [ 50%] index
Exception occurred:
File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/environment.py", line 1213, in get_doctree
f = open(doctree_filename, 'rb')
IOError: [Errno 2] No such file or directory: '/home/ricomoss/workspace/nextgen/docs/build/doctrees/index.doctree'
The full traceback has been saved in /tmp/sphinx-err-jjJ7gM.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.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
What is wrong, and how can I fix it?
Edit:
I'd like to be able to use a Makefile to handle this. As of now I have two folders in my project.
nextgen/ls
docs ys_utils
I need nextgen/docs/Makefile to generate the HTML for ys_utils and all other modules I'm going to have.
Autodoc can't find your modules, because they are not in sys.path.
You have to include the path to your modules in in the sys.path in your conf.py.
Look at the top of your conf.py (just after the import of sys), there is a sys.path.insert() statement, which you can adapt.
By the way: you can use the Makefile created by Sphinx to create your documentation.
Just call
make
to see the options.
If something went wrong before try:
make clean
before running make html.
solution
It sounds like os.path.append() is working OK for folks, but if you follow the conf.py template, you would insert the module path to the front of sys.path using os.path.insert(0, ...), and just add an extra .
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
If you have setup your sphinx project to use separate build and source directories, that call should instead be:
sys.path.insert(0, os.path.abspath('../..'))
about sys.path ...
To run python code, the python interpreter needs to know where it is. With the sphinx config being a python script, it's location needs to be made known, which is done by adding it the the sys.path variable using the insert method (see the docs on module search path).
The path added to sys.path in this case is a "relative" path, which is specified using dots. This is a general way of specifying the path, which allows the code to be moved and still point correctly to the correct path in your codebase.
. - current path of the conf.py
.. - parent path of the conf.py
../.. - parent of the parent path, etc.
I use linux, so directories are specified with a forward slash, but a cross-platform method for specifying parent directories can be acheived with pathlib.
from pathlib import Path
parent = Path(__file__).parent
parents_parent = Path(__file__).parents[1]
in conf.py
just add the path to your project folder.
sys.path.append('/home/workspace/myproj/myproj')
If
module root path is correctly set in conf.py
__init__.py is placed correctly
rst syntax is correct
and your autodoc still cannot find the modules...
It may be because the dependencies of those modules are not satisfied under your python environment. You will want to check if all the import statements are working within the modules.
I don't know why (maybe in my case autodoc couldn't install my package), but I always got module-not-found errors until I explicitly included all directories containing modules to the path.
For the following example folder structure
project_dir
|- setup.py
|- src
| |- __init__.py
| |- source1.py
| |- sub_project
| |- __init__.py
| |- source2.py
|- docs
|- conf.py
|- source
| |- index.rst
|- _build
I included
for x in os.walk('../../src'):
sys.path.insert(0, x[0])
to the beginning of conf.py such that all involved directories would be added.
I got this same error but it was caused by a completely different reason than explained in the other answers.
My .. automethod:: mymodule.func directive should actually have been:
.. automethod:: mymodule::func
See the New in version 1.3 section in the autoclass documentation.
i add the following line at the beggining of file conf.py:
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
sys.path.append(os.path.abspath(
os.path.join(__file__, "../../src")
))
my project has the next structure:
project_dir
|- setup.py
|- src
| |- __init__.py
| |- ....
|- docs
|- conf.py
|- ...
I think I did this the first time I tried to add a file to the toctree. I think it was because I left out the blank line between the :maxdepth line and the file name.
.. Animatrix Concepts documentation master file, created by
sphinx-quickstart on Thu Mar 22 18:06:15 2012.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Animatrix Concepts documentation!
============================================
Contents:
.. toctree::
:maxdepth: 2
stuff
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Above is my index.rst file. stuff.rst resides in the same directory as it.
You can use Pweave and noweb formatting to generate rst documents that include the output of the code embedded in them. Basically, you write your rst file, with python code embedded in marked chunks like this:
<<echo=False>>=
print("some text that will appear in the rst file")
#
and Pweave will execute those chunks, and replace them with their output in a resulting rst file, which you can then use with sphinx. See the Pweave reST example for more details of how it looks.
A lot of solutions in the thread are discussed in the right direction.
For me, the command on the official docs was helpful.
import pathlib
import sys
sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
Related
I met a very strange problem:
My file structure is like: (core and test are directories)
core
----file1.py
----__init__.py
test
----file2.py
in file2, i wrote:
from core import file1
result is:
ImportError: cannot import name file1
Have to create __init__.py file inside the test dir:
Because The __init__.py files are required to make Python treat the directories as containing packages.
parent/
child1/
__init__.py
file1.py
child2/
__init__.py
file2.py
From the error:
If run the child2/file2.py file directly. You are not able to access child1/file1.py from the child2/file2.py
Because only from the parent directory can access the child.
If have a folder structure like:
parent/
child1/
__init__.py
file1.py
child2/
__init__.py
file2.py
file3.py
If we run the file3.py file. Can able to access both child1/file1.py, child2/file2.py in file3.py
Because It is running from the parent directory.
If we need to access child1/file1 from child2/file2.py, We need to set the parent directory:
By running this below command we can achieve it...
PYTHONPATH=. python child2/file2.py
PYTHONPATH=. It refers the parent path. Then runs child2/file2.py file from the shell
It's not a strange problem, imports simply don't work like that.
From the official documentation: https://docs.python.org/3/tutorial/modules.html
When a module named spam is imported, the interpreter first searches for a built-in module with that name. If not found, it then searches for a file named spam.py in a list of directories given by the variable sys.path. sys.path is initialized from these locations:
The directory containing the input script (or the current directory when
no file is specified).
PYTHONPATH (a list of directory names, with the same syntax as the shell
variable PATH).
The installation-dependent default.
You could look into relative imports, here's a good source: https://stackoverflow.com/a/16985066/4886716
The relevant info from that post is that there's no good way to do it unless you add core to PYTHONPATH like Shawn. L says.
When I tried your case, I got
Traceback (most recent call last):
File "file2.py", line 3, in <module>
from core import file1
ImportError: No module named core
The reason is that Python does not find core. In this case, you need to add core to the system path, as shown below (add them at the very beginning of file2.py):
import sys,os
sys.path.append(path_to_core.py)
Or, if you would run it using command line, you could simply put the following at the beginning of file2.py
import sys,os
sys.path.append(os.path.join(os.path.dirname(__file__),'../'))
Here, os.path.join(os.path.dirname(__file__),'../') is to state the path to file2.py.
I have a python program in which I get the following error:
ImportError: No module named core
the import causing the error is:
from core import wcolors
the file wcolors.py is inside a dir named core, there is another dir called modules, so when i run my program it give this error output:
Traceback (most recent call last):
File "anubis.py", line 7, in <module>
from core import wcolors
ImportError: No module named core
dir structure
the dir structure follows like that
anubis
--anubis.py (the script that i run)
--core
--wcolors.py (the file i import from core)
-- modules
[the modules i suposed to load during the execution.]
as another detail all files in core are compiled with .pyc extention.
You just need to add a blank __init__.py to your anubis and anubis/core directories, and this should work. If you don’t have the __init__.py file, python will not think that the directory is a module.
The __init__.py files are required to make Python treat the directories as containing packages; this is done to prevent directories with a common name, such as string, from unintentionally hiding valid modules that occur later on the module search path. In the simplest case, __init__.py can just be an empty file
Python docs
You can try this:
from anubis.core import wcolors
OR you can change a name for "core", it could be a keyword for django and python.
I have a module I have installed called lts_fits, and this is its path:
~/Enthought/Canopy_64bit/User/lib/python2.7/site-packages/lts_fits
So it is clearly in the site packages folder. Within this folder, there is a python script:
lts_linefit.py
Yet when I have this line of code in my script:
from lts_fits import lts_linefit
I get this error:
ImportError: No module named lts_fits
How? It's clearly in there, and I have tried this same syntax with other random scripts and they import just fine. For instance, a file abc.py located in the folder ~/Enthought/Canopy_64bit/User/lib/python2.7/site-packages/sympy imports just fine when I have the line from sympy import abc. What could be going wrong?
You need an __init__.py file in that directory (you do not have to put anything into the file, all you need to do is create it).
The easiest way to create said file is by using:
touch __init__.py
from within your lts_fits directory in your command line/terminal/console.
See this SO article: What is __init__.py for?
And the Python Documentation for packages.
I have the following directory structure :
data __ __init__.py
|__ file1
|__ file2
script
README
MANIFEST.in
__init__.py
setup.py
The Python script script uses the data files in data. I am trying to make a source tarball for this script so that it can be used systemwide.
The __init__.py file is empty. The file 'script' invokes the data files through 'data/file1' and data/file2. The contents of MANIFEST.in are:
include README script
recursive-include data *
In setup.py, amongst other things, I have :
packages = ["data"],
package_data = ["data": "*"],
scripts = ["script"]
After setting up the distribution (using sdist), I tried installing it on my system. When I try using script, it says :
Traceback (most recent call last):
File "/home/nsoum/anaconda/bin/script", line 54, in <module>
with open('data/file1', 'r') as do:
IOError: [Errno 2] No such file or directory: 'data/file1'
I guess this means that the relative paths of the data-files is not preserved. How do I work around that and make sure that my script has access to the data files ?
Thank you.
What happens is that open('data/file1', 'r') operates relative to the current working directory of the process while the path is really relative to the code file. The best way to get at data files relative to the code distribution is to use setuptools rather than bare distutils for building and distributing your package. setuptools has API for getting at a package's data resource files.
I'm trying to run tests in my project in pycharm with the following structure:
root/
tests/
__init__.py
mytest.py
When I import my_settings from init.py into mytest.py, I got the following error:
Traceback (most recent call last):
File "/Applications/PyCharm.app/helpers/pycharm/utrunner.py", line 116, in <module> modules = [loadSource(a[0])]
File "/Applications/PyCharm.app/helpers/pycharm/utrunner.py", line 40, in loadSource module = imp.load_source(moduleName, fileName)
File "/Users/user/temp/test/tests/mytest.py", line 2, in <module> from tests import my_settings
ImportError: cannot import name my_settings
I can run test fine with the following command:
python -m unittest discover -s tests/
Here is a sample project: https://github.com/xcompass/pycharm-broken-test-path
I'm running pycharm 3.4.
This is far too late for the original poster, but I had exactly the same problem with PyCharm and thought putting my solution might help those that stumble across this via search.
One possible explanation for this problem, is that Python is not importing from the path you expect. Insert the following lines above the point where the ImportError occurs:
# using example module from above
import tests
print(tests.__file__)
Now re-run the tests in pycharm and examine the output.
What you may find, is that the path to the module "tests" is not what you expect. If that is the case, removing the errant module should fix it for you.
If that doesn't help, check the python path is what you expect by inserting the following lines above the error instead:
import sys
print(sys.path)
Also remove any build directories in your path, so you don't accidentally import a bad egg.
Finally, remove any *.pyc files from the directory:
find -name '*.pyc' -delete
This last one probably won't impact the problem above but caused py.test to fail for me after rebuilding a clean vagrant box.