Our current documentation says:
Building documentation ---------------------- The documentation is easy to build once deps are installed:: yum install python-sphinx To actually build the documentation:: cd docs/ make html
But that doesn't work, because we heavily recommend using virtualenv, and sphinx doesn't work when called from inside virtualenv. This is the result:
virtualenv
$ make html sphinx-build -b html -d build/doctrees source build/html Making output directory... Running Sphinx v1.1.3 loading pickled environment... not yet created building [html]: targets for 5 source files that are out of date updating environment: 5 added, 0 changed, 0 removed Traceback (most recent call last): File "/usr/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 321, in import_object __import__(self.modname) File "/home/kparal/devel/taskotron/libtaskotron/libtaskotron/bodhi_utils.py", line 13, in <module> from . import config File "/home/kparal/devel/taskotron/libtaskotron/libtaskotron/config.py", line 8, in <module> import yaml ImportError: No module named yaml Traceback (most recent call last): File "/usr/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 321, in import_object __import__(self.modname) File "/home/kparal/devel/taskotron/libtaskotron/libtaskotron/check.py", line 10, in <module> import tap ImportError: No module named tap Traceback (most recent call last): File "/usr/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 321, in import_object __import__(self.modname) File "/home/kparal/devel/taskotron/libtaskotron/libtaskotron/config.py", line 8, in <module> import yaml ImportError: No module named yaml Traceback (most recent call last): File "/usr/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 321, in import_object __import__(self.modname) File "/home/kparal/devel/taskotron/libtaskotron/libtaskotron/koji_utils.py", line 15, in <module> from libtaskotron import config File "/home/kparal/devel/taskotron/libtaskotron/libtaskotron/config.py", line 8, in <module> import yaml ImportError: No module named yaml Traceback (most recent call last): File "/usr/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 321, in import_object __import__(self.modname) File "/home/kparal/devel/taskotron/libtaskotron/libtaskotron/runner.py", line 9, in <module> from libtaskotron import taskyaml File "/home/kparal/devel/taskotron/libtaskotron/libtaskotron/taskyaml.py", line 1, in <module> import yaml ImportError: No module named yaml Traceback (most recent call last): File "/usr/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 321, in import_object __import__(self.modname) File "/home/kparal/devel/taskotron/libtaskotron/libtaskotron/yumrepoinfo.py", line 10, in <module> from . import config File "/home/kparal/devel/taskotron/libtaskotron/libtaskotron/config.py", line 8, in <module> import yaml ImportError: No module named yaml reading sources... [100%] writingtasks /home/kparal/devel/taskotron/libtaskotron/docs/source/library.rst:17: WARNING: autodoc can't import/find module 'libtaskotron.bodhi_utils', it reported error: "No module named yaml", please check your spelling and sys.path /home/kparal/devel/taskotron/libtaskotron/docs/source/library.rst:23: WARNING: autodoc can't import/find module 'libtaskotron.check', it reported error: "No module named tap", please check your spelling and sys.path /home/kparal/devel/taskotron/libtaskotron/docs/source/library.rst:29: WARNING: autodoc can't import/find module 'libtaskotron.config', it reported error: "No module named yaml", please check your spelling and sys.path /home/kparal/devel/taskotron/libtaskotron/docs/source/library.rst:53: WARNING: autodoc can't import/find module 'libtaskotron.koji_utils', it reported error: "No module named yaml", please check your spelling and sys.path /home/kparal/devel/taskotron/libtaskotron/docs/source/library.rst:77: WARNING: autodoc can't import/find module 'libtaskotron.runner', it reported error: "No module named yaml", please check your spelling and sys.path /home/kparal/devel/taskotron/libtaskotron/docs/source/library.rst:83: WARNING: autodoc can't import/find module 'libtaskotron.yumrepoinfo', it reported error: "No module named yaml", please check your spelling and sys.path looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] writingtasks writing additional files... genindex py-modindex search copying static files... WARNING: html_static_path entry '/home/kparal/devel/taskotron/libtaskotron/docs/source/_static' does not exist done dumping search index... done dumping object inventory... done build succeeded, 7 warnings. Build finished. The HTML pages are in build/html.
The problem is reported here: https://bitbucket.org/birkenfeld/sphinx/issue/1454/call-the-correct-interpreter-under
Please adjust the docs and clarify that sphinx needs to be installed inside virtualenv, and link that bug report as the reason. Also add sphinx to the list of dependencies in requirements.txt, if it's not there already.
requirements.txt
Test that everything works in a fresh environment according to your adjusted documentation.
This ticket had assigned some Differential requests: D131
Metadata Update from @kparal: - Issue tagged with: easyfix
Login to comment on this ticket.