sphinx-build fails with DistributionNotFound exception

[vitaut]

Running sphinx-build --version fails with the following output:

Traceback (most recent call last):
  File "/home/travis/build/cppformat/cppformat/virtualenv/bin/sphinx-build", line 5, in <module>
    from pkg_resources import load_entry_point
  File "/home/travis/build/cppformat/cppformat/virtualenv/local/lib/python2.7/site-packages/distribute-0.6.24-py2.7.egg/pkg_resources.py", line 2707, in <module>
    working_set.require(__requires__)
  File "/home/travis/build/cppformat/cppformat/virtualenv/local/lib/python2.7/site-packages/distribute-0.6.24-py2.7.egg/pkg_resources.py", line 686, in require
    needed = self.resolve(parse_requirements(requirements))
  File "/home/travis/build/cppformat/cppformat/virtualenv/local/lib/python2.7/site-packages/distribute-0.6.24-py2.7.egg/pkg_resources.py", line 584, in resolve
    raise DistributionNotFound(req)
pkg_resources.DistributionNotFound: sphinx-rtd-theme>=0.1,<2.0

I'm using version git+git://github.com/sphinx-doc/sphinx.git@4d2c17e043d9e8197fa5cd0db34212af3bb17069.

BTW I'm not using sphinx-rtd-theme. Why is it required by Sphinx?

[tk0miya]

In my environment, it does not be reproduced.

$ virtualenv bar
New python executable in bar/bin/python2.7
Also creating executable in bar/bin/python
Installing setuptools, pip, wheel...done.
$ . bar/bin/activate
$ pip install git+git://github.com/sphinx-doc/sphinx.git@4d2c17e043d9e8197fa5cd0db34212af3bb17069
Collecting git+git://github.com/sphinx-doc/sphinx.git@4d2c17e043d9e8197fa5cd0db34212af3bb17069
  Cloning git://github.com/sphinx-doc/sphinx.git (to 4d2c17e043d9e8197fa5cd0db34212af3bb17069) to /var/folders/2s/79pf79d94r9gxhzl4kpztrr00000gp/T/pip-HmptSz-build
  Could not find a tag or branch '4d2c17e043d9e8197fa5cd0db34212af3bb17069', assuming commit.
Collecting six>=1.4 (from Sphinx==1.4a0.dev20160103)
  Using cached six-1.10.0-py2.py3-none-any.whl
Collecting Jinja2>=2.3 (from Sphinx==1.4a0.dev20160103)
  Using cached Jinja2-2.8-py2.py3-none-any.whl
Collecting Pygments>=2.0 (from Sphinx==1.4a0.dev20160103)
  Using cached Pygments-2.0.2-py2-none-any.whl
Collecting docutils>=0.11 (from Sphinx==1.4a0.dev20160103)
Collecting snowballstemmer>=1.1 (from Sphinx==1.4a0.dev20160103)
  Using cached snowballstemmer-1.2.1-py2.py3-none-any.whl
Collecting babel!=2.0,>=1.3 (from Sphinx==1.4a0.dev20160103)
  Downloading Babel-2.2.0-py2.py3-none-any.whl (6.5MB)
    100% |████████████████████████████████| 6.5MB 55kB/s
Collecting alabaster<0.8,>=0.7 (from Sphinx==1.4a0.dev20160103)
  Using cached alabaster-0.7.7-py2.py3-none-any.whl
Collecting sphinx-rtd-theme<2.0,>=0.1 (from Sphinx==1.4a0.dev20160103)
  Using cached sphinx_rtd_theme-0.1.9-py2-none-any.whl
Collecting MarkupSafe (from Jinja2>=2.3->Sphinx==1.4a0.dev20160103)
Collecting pytz>=0a (from babel!=2.0,>=1.3->Sphinx==1.4a0.dev20160103)
  Using cached pytz-2015.7-py2.py3-none-any.whl
Installing collected packages: six, MarkupSafe, Jinja2, Pygments, docutils, snowballstemmer, pytz, babel, alabaster, sphinx-rtd-theme, Sphinx
  Running setup.py install for Sphinx
Successfully installed Jinja2-2.8 MarkupSafe-0.23 Pygments-2.0.2 Sphinx-1.4a0.dev20160103 alabaster-0.7.7 babel-2.2.0 docutils-0.12 pytz-2015.7 six-1.10.0 snowballstemmer-1.2.1 sphinx-rtd-theme-0.1.9
$ hash -r
$ sphinx-build --version
Sphinx (sphinx-build) 1.4a0+

It looks the Sphinx you use depends on sphinx_rtd_theme. So, I wonder why the package is not installed on your environment.
Could you check it again, please?

[vitaut]

It happens at least with the distribute package version 0.6.24 which is installed on Travis:

$ virtualenv bar
$ cd bar
$ . bin/activate
$ pip install distribute==0.6.24
$ pip install git+git://github.com/sphinx-doc/sphinx.git@4d2c17e043d9e8197fa5cd0db34212af3bb17069
...
$ sphinx-build --version
Traceback (most recent call last):
  File "/tmp/bar/bin/sphinx-build", line 5, in <module>
    from pkg_resources import load_entry_point
  File "/tmp/bar/local/lib/python2.7/site-packages/pkg_resources.py", line 2707, in <module>
    working_set.require(__requires__)
  File "/tmp/bar/local/lib/python2.7/site-packages/pkg_resources.py", line 686, in require
    needed = self.resolve(parse_requirements(requirements))
  File "/tmp/bar/local/lib/python2.7/site-packages/pkg_resources.py", line 584, in resolve
    raise DistributionNotFound(req)
pkg_resources.DistributionNotFound: sphinx-rtd-theme>=0.1,<2.0

As a workaround I update distribute manually now (fmtlib/fmt@aaa8b1e), but it would be nice if sphinx-rtd-theme was optional and didn't break installation of Sphinx without updating distribute.

[tk0miya]

I understand. I'll think about #2087 later.
but it will be introduced in next major version if the theme was deprecated. so, for now, we should use the workaround...

[vitaut]

but it will be introduced in next major version if the theme was deprecated.

That's fine, I'm using unreleased version anyway. For now the workaround will do.

[acsr]

For me having this error the issue was that sphinx-quickstart failed to write a proper working default path to the sphinx-build executable in the variable SPHINXBUILD in the makefile. It assumes that the local sphinx-build is already in the current path.

In my case the make command used a wrong sphinx-build command from another path (here: system Python).

Steps to reproduce

I created a virtualenv but did not activate it. I usually explicitly pass the path to the Python executable during install of the venv I use.

Then I used the explicit pip of the venv to install Sphinx::

[path-to-my-venv]/bin/pip install Sphinx

Thats seems not enough for the install using pip to set things up and for a proper build of the sphinx-quickstart command.

The initial default in the makefile was::

SPHINXBUILD   = sphinx-build

The default path during shell execution was going to the system Python, not the venv. This usually may have no module sphinx-rtd-theme in a proper version.

Note: When you check the modules of the venv you may also find the modulename sphinx_rtd_theme using underscores! Not sure if this matters in other situations.

Workaround

A workaround solution for me was to give the explicit path to the executable in the makefile without fiddling with the $PATH::

SPHINXBUILD   = [path-to-my-venv]/bin/sphinx-build

note

I usually do not check in the makefiles into repos, so this does not hurt me.

Even if I failed to follow all best practise, maybe it is helpful if someone needs to drill deeper to make the quickstart more reliable for newbies in this case.