#132 docs: clarify that sphinx needs to be installed in virtualenv
Closed: Fixed None Opened 9 years ago by kparal.

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:

$ 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.

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

6 years ago

Login to comment on this ticket.

Metadata